Merge pull request #201 from orklah/master

bump phpstan to master

.github/workflows/push.yml

@@ -127,7 +127,7 @@ jobs:
             all-build-${{ hashFiles('**/composer.lock') }}
             all-build-
       - name: Code style check
-        uses: phpDocumentor/coding-standard@v1.0.0
+        uses: phpDocumentor/coding-standard@master
         with:
           args: -s
 
@@ -149,7 +149,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          args: analyse src --level max --configuration phpstan.neon
+          args: analyse src --configuration phpstan.neon
 
   psalm:
     runs-on: ubuntu-latest

Makefile

@@ -21,7 +21,7 @@ phpcbf:
 
 .PHONY: phpstan
 phpstan:
-	docker run -it --rm -v${PWD}:/opt/project -w /opt/project phpdoc/phpstan-ga:latest analyse src --no-progress --level max --configuration phpstan.neon
+	docker run -it --rm -v${PWD}:/opt/project -w /opt/project phpdoc/phpstan-ga:latest analyse src --no-progress --configuration phpstan.neon
 
 .PHONY: psaml
 psalm:

phpstan.neon

@@ -3,6 +3,6 @@ includes:
     - /composer/vendor/phpstan/phpstan-webmozart-assert/extension.neon
 
 parameters:
+    level: max
     ignoreErrors:
-        # false positive
+        - '#Call to static method Webmozart\\Assert\\Assert::implementsInterface\(\) with class-string#'
-        - '#Method phpDocumentor\Reflection\DocBlock\Tags\Method::filterArguments() should return array<array> but returns array<array|string>#'

psalm.xml

@@ -14,5 +14,12 @@
 
     <issueHandlers>
         <LessSpecificReturnType errorLevel="info" />
+        
+        <RedundantConditionGivenDocblockType>
+            <errorLevel type="info">
+                <!-- Psalm is very strict and believe that because we documented a type, it is redundant to assert it -->
+                <file name="src/DocBlock/StandardTagFactory.php"/>
+            </errorLevel>
+        </RedundantConditionGivenDocblockType>
     </issueHandlers>
 </psalm>

src/DocBlock.php

@@ -150,7 +150,6 @@ final class DocBlock
     {
         $result = [];
 
-        /** @var Tag $tag */
         foreach ($this->getTags() as $tag) {
             if ($tag->getName() !== $name) {
                 continue;
@@ -169,7 +168,6 @@ final class DocBlock
      */
     public function hasTag(string $name) : bool
     {
-        /** @var Tag $tag */
         foreach ($this->getTags() as $tag) {
             if ($tag->getName() === $name) {
                 return true;

src/DocBlock/DescriptionFactory.php

@@ -15,7 +15,6 @@ namespace phpDocumentor\Reflection\DocBlock;
 
 use phpDocumentor\Reflection\Types\Context as TypeContext;
 use Webmozart\Assert\Assert;
-use const PREG_SPLIT_DELIM_CAPTURE;
 use function count;
 use function explode;
 use function implode;
@@ -27,6 +26,7 @@ use function strlen;
 use function strpos;
 use function substr;
 use function trim;
+use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**
  * Creates a new Description object given a body of text.
@@ -128,6 +128,7 @@ class DescriptionFactory
             PREG_SPLIT_DELIM_CAPTURE
         );
         Assert::isArray($parts);
+
         return $parts;
     }
 

src/DocBlock/ExampleFinder.php

@@ -14,7 +14,6 @@ declare(strict_types=1);
 namespace phpDocumentor\Reflection\DocBlock;
 
 use phpDocumentor\Reflection\DocBlock\Tags\Example;
-use const DIRECTORY_SEPARATOR;
 use function array_slice;
 use function file;
 use function getcwd;
@@ -23,6 +22,7 @@ use function is_readable;
 use function rtrim;
 use function sprintf;
 use function trim;
+use const DIRECTORY_SEPARATOR;
 
 /**
  * Class used to find an example file's location based on a given ExampleDescriptor.
@@ -122,6 +122,7 @@ class ExampleFinder
         }
 
         $lines = $normalizedPath && is_readable($normalizedPath) ? file($normalizedPath) : false;
+
         return $lines !== false ? $lines : null;
     }
 

src/DocBlock/Serializer.php

@@ -94,6 +94,7 @@ class Serializer
         }
 
         $comment = $this->addTagBlock($docblock, $wrapLength, $indent, $comment);
+
         return $comment . $indent . ' */';
     }
 
@@ -127,6 +128,7 @@ class Serializer
                 : '');
         if ($wrapLength !== null) {
             $text = wordwrap($text, $wrapLength);
+
             return $text;
         }
 

src/DocBlock/StandardTagFactory.php

@@ -71,7 +71,7 @@ final class StandardTagFactory implements TagFactory
     public const REGEX_TAGNAME = '[\w\-\_\\\\:]+';
 
     /**
-     * @var string[] An array with a tag as a key, and an
+     * @var array<class-string<StaticMethod>> An array with a tag as a key, and an
      *                                        FQCN to a class that handles it as an array value.
      */
     private $tagHandlerMappings = [
@@ -97,7 +97,7 @@ final class StandardTagFactory implements TagFactory
     ];
 
     /**
-     * @var string[] An array with a anotation s a key, and an
+     * @var array<class-string<StaticMethod>> An array with a anotation s a key, and an
      *      FQCN to a class that handles it as an array value.
      */
     private $annotationMappings = [];
@@ -125,7 +125,7 @@ final class StandardTagFactory implements TagFactory
      *
      * @see self::registerTagHandler() to add a new tag handler to the existing default list.
      *
-     * @param string[] $tagHandlers
+     * @param array<class-string<StaticMethod>> $tagHandlers
      */
     public function __construct(FqsenResolver $fqsenResolver, ?array $tagHandlers = null)
     {
@@ -137,9 +137,6 @@ final class StandardTagFactory implements TagFactory
         $this->addService($fqsenResolver, FqsenResolver::class);
     }
 
-    /**
-     * {@inheritDoc}
-     */
     public function create(string $tagLine, ?TypeContext $context = null) : Tag
     {
         if (!$context) {
@@ -152,29 +149,22 @@ final class StandardTagFactory implements TagFactory
     }
 
     /**
-     * {@inheritDoc}
+     * @param mixed $value
      */
     public function addParameter(string $name, $value) : void
     {
         $this->serviceLocator[$name] = $value;
     }
 
-    /**
-     * {@inheritDoc}
-     */
     public function addService(object $service, ?string $alias = null) : void
     {
         $this->serviceLocator[$alias ?: get_class($service)] = $service;
     }
 
-    /**
-     * {@inheritDoc}
-     */
     public function registerTagHandler(string $tagName, string $handler) : void
     {
         Assert::stringNotEmpty($tagName);
         Assert::classExists($handler);
-        /** @var object $handler stupid hack to make phpstan happy.  */
         Assert::implementsInterface($handler, StaticMethod::class);
 
         if (strpos($tagName, '\\') && $tagName[0] !== '\\') {
@@ -220,9 +210,10 @@ final class StandardTagFactory implements TagFactory
         );
 
         try {
-            /** @var callable $callable */
             $callable = [$handlerClassName, 'create'];
+            Assert::isCallable($callable);
             $tag = call_user_func_array($callable, $arguments);
+
             return $tag ?? InvalidTag::create($body, $name);
         } catch (InvalidArgumentException $e) {
             return InvalidTag::create($body, $name)->withError($e);

src/DocBlock/TagFactory.php

@@ -14,6 +14,7 @@ declare(strict_types=1);
 namespace phpDocumentor\Reflection\DocBlock;
 
 use InvalidArgumentException;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\StaticMethod;
 use phpDocumentor\Reflection\Types\Context as TypeContext;
 
 interface TagFactory
@@ -69,9 +70,9 @@ interface TagFactory
      * to register the name of a tag with the FQCN of a 'Tag Handler'. The Tag handler should implement
      * the {@see Tag} interface (and thus the create method).
      *
-     * @param string $tagName Name of tag to register a handler for. When registering a namespaced tag,
+     * @param string                     $tagName Name of tag to register a handler for. When registering a namespaced
-     *                        the full name, along with a prefixing slash MUST be provided.
+     *                                   tag, the full name, along with a prefixing slash MUST be provided.
-     * @param string $handler FQCN of handler.
+     * @param class-string<StaticMethod> $handler FQCN of handler.
      *
      * @throws InvalidArgumentException If the tag name is not a string.
      * @throws InvalidArgumentException If the tag name is namespaced (contains backslashes) but

src/DocBlock/Tags/Author.php

@@ -14,11 +14,11 @@ declare(strict_types=1);
 namespace phpDocumentor\Reflection\DocBlock\Tags;
 
 use InvalidArgumentException;
-use const FILTER_VALIDATE_EMAIL;
 use function filter_var;
 use function preg_match;
 use function strlen;
 use function trim;
+use const FILTER_VALIDATE_EMAIL;
 
 /**
  * Reflection class for an {@}author tag in a Docblock.

src/DocBlock/Tags/Covers.php

@@ -41,9 +41,6 @@ final class Covers extends BaseTag implements Factory\StaticMethod
         $this->description = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?DescriptionFactory $descriptionFactory = null,

src/DocBlock/Tags/Deprecated.php

@@ -75,6 +75,7 @@ final class Deprecated extends BaseTag implements Factory\StaticMethod
         }
 
         Assert::notNull($descriptionFactory);
+
         return new static(
             $matches[1],
             $descriptionFactory->create($matches[2] ?? '', $context)

src/DocBlock/Tags/Example.php

@@ -82,9 +82,6 @@ final class Example implements Tag, Factory\StaticMethod
         return $this->content;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(string $body) : ?Tag
     {
         // File component: File path in quotes or File URI / Source information

src/DocBlock/Tags/Link.php

@@ -39,9 +39,6 @@ final class Link extends BaseTag implements Factory\StaticMethod
         $this->description = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?DescriptionFactory $descriptionFactory = null,

src/DocBlock/Tags/Method.php

@@ -44,7 +44,10 @@ final class Method extends BaseTag implements Factory\StaticMethod
     /** @var string */
     private $methodName = '';
 
-    /** @var string[][] */
+    /**
+     * @phpstan-var array<int, array{name: string, type: Type}>
+     * @var array<int, array<string, Type|string>>
+     */
     private $arguments = [];
 
     /** @var bool */
@@ -54,9 +57,9 @@ final class Method extends BaseTag implements Factory\StaticMethod
     private $returnType;
 
     /**
-     * @param mixed[][] $arguments
+     * @param array<int, array<string, Type|string>> $arguments
      *
-     * @psalm-param array<int, array<string, string|Type>|string> $arguments
+     * @phpstan-param array<int, array{name: string, type: Type}|string> $arguments
      */
     public function __construct(
         string $methodName,
@@ -78,9 +81,6 @@ final class Method extends BaseTag implements Factory\StaticMethod
         $this->description = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?TypeResolver $typeResolver = null,
@@ -137,7 +137,7 @@ final class Method extends BaseTag implements Factory\StaticMethod
             return null;
         }
 
-        [, $static, $returnType, $methodName, $arguments, $description] = $matches;
+        [, $static, $returnType, $methodName, $argumentLines, $description] = $matches;
 
         $static = $static === 'static';
 
@@ -148,9 +148,11 @@ final class Method extends BaseTag implements Factory\StaticMethod
         $returnType  = $typeResolver->resolve($returnType, $context);
         $description = $descriptionFactory->create($description, $context);
 
-        if ($arguments !== '') {
+        /** @phpstan-var array<int, array{name: string, type: Type}> $arguments */
-            $arguments = explode(',', $arguments);
+        $arguments = [];
-            foreach ($arguments as &$argument) {
+        if ($argumentLines !== '') {
+            $argumentsExploded = explode(',', $argumentLines);
+            foreach ($argumentsExploded as $argument) {
                 $argument = explode(' ', self::stripRestArg(trim($argument)), 2);
                 if ($argument[0][0] === '$') {
                     $argumentName = substr($argument[0], 1);
@@ -164,10 +166,8 @@ final class Method extends BaseTag implements Factory\StaticMethod
                     }
                 }
 
-                $argument = ['name' => $argumentName, 'type' => $argumentType];
+                $arguments[] = ['name' => $argumentName, 'type' => $argumentType];
             }
-        } else {
-            $arguments = [];
         }
 
         return new static($methodName, $arguments, $returnType, $static, $description);
@@ -182,7 +182,9 @@ final class Method extends BaseTag implements Factory\StaticMethod
     }
 
     /**
-     * @return string[][]
+     * @return array<int, array<string, Type|string>>
+     *
+     * @phpstan-return array<int, array{name: string, type: Type}>
      */
     public function getArguments() : array
     {
@@ -223,8 +225,8 @@ final class Method extends BaseTag implements Factory\StaticMethod
      *
      * @return mixed[][]
      *
-     * @psalm-param array<int, array<string, string|Type>|string> $arguments
+     * @phpstan-param array<int, array{name: string, type: Type}|string> $arguments
-     * @psalm-return array<int, array<string, string|Type>> $arguments
+     * @phpstan-return array<int, array{name: string, type: Type}>
      */
     private function filterArguments(array $arguments = []) : array
     {

src/DocBlock/Tags/Param.php

@@ -19,7 +19,6 @@ use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\TypeResolver;
 use phpDocumentor\Reflection\Types\Context as TypeContext;
 use Webmozart\Assert\Assert;
-use const PREG_SPLIT_DELIM_CAPTURE;
 use function array_shift;
 use function array_unshift;
 use function implode;
@@ -27,6 +26,7 @@ use function preg_split;
 use function strlen;
 use function strpos;
 use function substr;
+use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**
  * Reflection class for the {@}param tag in a Docblock.
@@ -52,9 +52,6 @@ final class Param extends TagWithType implements Factory\StaticMethod
         $this->description  = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?TypeResolver $typeResolver = null,
@@ -69,6 +66,7 @@ final class Param extends TagWithType implements Factory\StaticMethod
 
         $type         = null;
         $parts        = preg_split('/(\s+)/Su', $body, 2, PREG_SPLIT_DELIM_CAPTURE);
+        Assert::isArray($parts);
         $variableName = '';
         $isVariadic   = false;
 

src/DocBlock/Tags/Property.php

@@ -19,7 +19,6 @@ use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\TypeResolver;
 use phpDocumentor\Reflection\Types\Context as TypeContext;
 use Webmozart\Assert\Assert;
-use const PREG_SPLIT_DELIM_CAPTURE;
 use function array_shift;
 use function array_unshift;
 use function implode;
@@ -27,6 +26,7 @@ use function preg_split;
 use function strlen;
 use function strpos;
 use function substr;
+use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**
  * Reflection class for a {@}property tag in a Docblock.
@@ -46,9 +46,6 @@ final class Property extends TagWithType implements Factory\StaticMethod
         $this->description  = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?TypeResolver $typeResolver = null,
@@ -62,6 +59,7 @@ final class Property extends TagWithType implements Factory\StaticMethod
         [$firstPart, $body] = self::extractTypeFromBody($body);
         $type               = null;
         $parts              = preg_split('/(\s+)/Su', $body, 2, PREG_SPLIT_DELIM_CAPTURE);
+        Assert::isArray($parts);
         $variableName = '';
 
         // if the first item that is encountered is not a variable; it is a type

src/DocBlock/Tags/PropertyRead.php

@@ -19,7 +19,6 @@ use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\TypeResolver;
 use phpDocumentor\Reflection\Types\Context as TypeContext;
 use Webmozart\Assert\Assert;
-use const PREG_SPLIT_DELIM_CAPTURE;
 use function array_shift;
 use function array_unshift;
 use function implode;
@@ -27,6 +26,7 @@ use function preg_split;
 use function strlen;
 use function strpos;
 use function substr;
+use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**
  * Reflection class for a {@}property-read tag in a Docblock.
@@ -46,9 +46,6 @@ final class PropertyRead extends TagWithType implements Factory\StaticMethod
         $this->description  = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?TypeResolver $typeResolver = null,
@@ -62,6 +59,7 @@ final class PropertyRead extends TagWithType implements Factory\StaticMethod
         [$firstPart, $body] = self::extractTypeFromBody($body);
         $type               = null;
         $parts              = preg_split('/(\s+)/Su', $body, 2, PREG_SPLIT_DELIM_CAPTURE);
+        Assert::isArray($parts);
         $variableName = '';
 
         // if the first item that is encountered is not a variable; it is a type

src/DocBlock/Tags/PropertyWrite.php

@@ -19,7 +19,6 @@ use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\TypeResolver;
 use phpDocumentor\Reflection\Types\Context as TypeContext;
 use Webmozart\Assert\Assert;
-use const PREG_SPLIT_DELIM_CAPTURE;
 use function array_shift;
 use function array_unshift;
 use function implode;
@@ -27,6 +26,7 @@ use function preg_split;
 use function strlen;
 use function strpos;
 use function substr;
+use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**
  * Reflection class for a {@}property-write tag in a Docblock.
@@ -46,9 +46,6 @@ final class PropertyWrite extends TagWithType implements Factory\StaticMethod
         $this->description  = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?TypeResolver $typeResolver = null,
@@ -62,6 +59,7 @@ final class PropertyWrite extends TagWithType implements Factory\StaticMethod
         [$firstPart, $body] = self::extractTypeFromBody($body);
         $type               = null;
         $parts              = preg_split('/(\s+)/Su', $body, 2, PREG_SPLIT_DELIM_CAPTURE);
+        Assert::isArray($parts);
         $variableName = '';
 
         // if the first item that is encountered is not a variable; it is a type

src/DocBlock/Tags/Return_.php

@@ -32,9 +32,6 @@ final class Return_ extends TagWithType implements Factory\StaticMethod
         $this->description = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?TypeResolver $typeResolver = null,

src/DocBlock/Tags/See.php

@@ -44,9 +44,6 @@ final class See extends BaseTag implements Factory\StaticMethod
         $this->description = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?FqsenResolver $typeResolver = null,

src/DocBlock/Tags/Since.php

@@ -69,6 +69,7 @@ final class Since extends BaseTag implements Factory\StaticMethod
         }
 
         Assert::notNull($descriptionFactory);
+
         return new static(
             $matches[1],
             $descriptionFactory->create($matches[2] ?? '', $context)

src/DocBlock/Tags/Source.php

@@ -47,9 +47,6 @@ final class Source extends BaseTag implements Factory\StaticMethod
         $this->description  = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?DescriptionFactory $descriptionFactory = null,

src/DocBlock/Tags/Throws.php

@@ -32,9 +32,6 @@ final class Throws extends TagWithType implements Factory\StaticMethod
         $this->description = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?TypeResolver $typeResolver = null,

src/DocBlock/Tags/Uses.php

@@ -41,9 +41,6 @@ final class Uses extends BaseTag implements Factory\StaticMethod
         $this->description = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?FqsenResolver $resolver = null,

src/DocBlock/Tags/Var_.php

@@ -19,7 +19,6 @@ use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\TypeResolver;
 use phpDocumentor\Reflection\Types\Context as TypeContext;
 use Webmozart\Assert\Assert;
-use const PREG_SPLIT_DELIM_CAPTURE;
 use function array_shift;
 use function array_unshift;
 use function implode;
@@ -27,6 +26,7 @@ use function preg_split;
 use function strlen;
 use function strpos;
 use function substr;
+use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**
  * Reflection class for a {@}var tag in a Docblock.
@@ -46,9 +46,6 @@ final class Var_ extends TagWithType implements Factory\StaticMethod
         $this->description  = $description;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public static function create(
         string $body,
         ?TypeResolver $typeResolver = null,
@@ -62,6 +59,7 @@ final class Var_ extends TagWithType implements Factory\StaticMethod
         [$firstPart, $body] = self::extractTypeFromBody($body);
 
         $parts = preg_split('/(\s+)/Su', $body, 2, PREG_SPLIT_DELIM_CAPTURE);
+        Assert::isArray($parts);
         $type         = null;
         $variableName = '';
 
@@ -102,7 +100,7 @@ final class Var_ extends TagWithType implements Factory\StaticMethod
     public function __toString() : string
     {
         return ($this->type ? $this->type . ' ' : '')
-            . (empty($this->variableName) ? '' : ('$' . $this->variableName))
+            . (empty($this->variableName) ? '' : '$' . $this->variableName)
             . ($this->description ? ' ' . $this->description : '');
     }
 }

src/DocBlockFactory.php

@@ -18,6 +18,7 @@ use LogicException;
 use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
 use phpDocumentor\Reflection\DocBlock\StandardTagFactory;
 use phpDocumentor\Reflection\DocBlock\TagFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\StaticMethod;
 use Webmozart\Assert\Assert;
 use function array_shift;
 use function count;
@@ -51,7 +52,7 @@ final class DocBlockFactory implements DocBlockFactoryInterface
     /**
      * Factory method for easy instantiation.
      *
-     * @param string[] $additionalTags
+     * @param array<class-string<StaticMethod>> $additionalTags
      */
     public static function createInstance(array $additionalTags = []) : self
     {
@@ -79,6 +80,7 @@ final class DocBlockFactory implements DocBlockFactoryInterface
         if (is_object($docblock)) {
             if (!method_exists($docblock, 'getDocComment')) {
                 $exceptionMessage = 'Invalid object passed; the given object must support the getDocComment method';
+
                 throw new InvalidArgumentException($exceptionMessage);
             }
 
@@ -106,6 +108,9 @@ final class DocBlockFactory implements DocBlockFactoryInterface
         );
     }
 
+    /**
+     * @param class-string<StaticMethod> $handler
+     */
     public function registerTagHandler(string $tagName, string $handler) : void
     {
         $this->tagFactory->registerTagHandler($tagName, $handler);
@@ -118,8 +123,8 @@ final class DocBlockFactory implements DocBlockFactoryInterface
      */
     private function stripDocComment(string $comment) : string
     {
-        /** @var string $comment */
         $comment = preg_replace('#[ \t]*(?:\/\*\*|\*\/|\*)?[ \t]{0,1}(.*)?#u', '$1', $comment);
+        Assert::string($comment);
         $comment = trim($comment);
 
         // reg ex above is not able to remove */ from a single line docblock
@@ -130,7 +135,7 @@ final class DocBlockFactory implements DocBlockFactoryInterface
         return str_replace(["\r\n", "\r"], "\n", $comment);
     }
 
-    // phpcs:disable SlevomatCodingStandard.Commenting.ForbiddenAnnotations.AnnotationForbidden
+    // phpcs:disable
     /**
      * Splits the DocBlock into a template marker, summary, description and block of tags.
      *
@@ -144,6 +149,7 @@ final class DocBlockFactory implements DocBlockFactoryInterface
      */
     private function splitDocBlock(string $comment) : array
     {
+        // phpcs:enable
         // Performance improvement cheat: if the first character is an @ then only tags are in this DocBlock. This
         // method does not split tags so we return this verbatim as the fourth result (tags). This saves us the
         // performance impact of running a regular expression
@@ -152,9 +158,8 @@ final class DocBlockFactory implements DocBlockFactoryInterface
         }
 
         // clears all extra horizontal whitespace from the line endings to prevent parsing issues
-        /** @var string $comment */
         $comment = preg_replace('/\h*$/Sum', '', $comment);
-
+        Assert::string($comment);
         /*
          * Splits the docblock into a template marker, summary, description and tags section.
          *
@@ -247,11 +252,11 @@ final class DocBlockFactory implements DocBlockFactoryInterface
     private function splitTagBlockIntoTagLines(string $tags) : array
     {
         $result = [];
-        foreach (explode("\n", $tags) as $tag_line) {
+        foreach (explode("\n", $tags) as $tagLine) {
-            if (isset($tag_line[0]) && ($tag_line[0] === '@')) {
+            if (isset($tagLine[0]) && ($tagLine[0] === '@')) {
-                $result[] = $tag_line;
+                $result[] = $tagLine;
             } else {
-                $result[count($result) - 1] .= "\n" . $tag_line;
+                $result[count($result) - 1] .= "\n" . $tagLine;
             }
         }
 
@@ -269,7 +274,9 @@ final class DocBlockFactory implements DocBlockFactoryInterface
             // @codeCoverageIgnoreStart
             // Can't simulate this; this only happens if there is an error with the parsing of the DocBlock that
             // we didn't foresee.
+
             throw new LogicException('A tag block started with text instead of an at-sign(@): ' . $tags);
+
             // @codeCoverageIgnoreEnd
         }
 

src/DocBlockFactoryInterface.php

@@ -4,13 +4,15 @@ declare(strict_types=1);
 
 namespace phpDocumentor\Reflection;
 
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\StaticMethod;
+
 // phpcs:ignore SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming.SuperfluousSuffix
 interface DocBlockFactoryInterface
 {
     /**
      * Factory method for easy instantiation.
      *
-     * @param string[] $additionalTags
+     * @param array<class-string<StaticMethod>> $additionalTags
      */
     public static function createInstance(array $additionalTags = []) : DocBlockFactory;
 

tests/unit/DocBlock/StandardTagFactoryTest.php

@@ -68,7 +68,6 @@ class StandardTagFactoryTest extends TestCase
         $tagFactory = new StandardTagFactory(m::mock(FqsenResolver::class));
         $tagFactory->addService($descriptionFactory, DescriptionFactory::class);
 
-        /** @var Generic $tag */
         $tag = $tagFactory->create('@' . $expectedTagName . ' This is a description', $context);
 
         $this->assertInstanceOf(Generic::class, $tag);
@@ -89,7 +88,6 @@ class StandardTagFactoryTest extends TestCase
         $context    = new Context('');
         $tagFactory = new StandardTagFactory(m::mock(FqsenResolver::class));
 
-        /** @var Author $tag */
         $tag = $tagFactory->create('@author Mike van Riel <[email protected]>', $context);
 
         $this->assertInstanceOf(Author::class, $tag);
@@ -120,7 +118,6 @@ class StandardTagFactoryTest extends TestCase
         $tagFactory = new StandardTagFactory($resolver);
         $tagFactory->addService($descriptionFactory, DescriptionFactory::class);
 
-        /** @var See $tag */
         $tag = $tagFactory->create('@see Tag');
 
         $this->assertInstanceOf(See::class, $tag);
@@ -140,7 +137,6 @@ class StandardTagFactoryTest extends TestCase
         $context    = new Context('');
         $tagFactory = new StandardTagFactory(m::mock(FqsenResolver::class), ['user' => Author::class]);
 
-        /** @var Author $tag */
         $tag = $tagFactory->create('@user Mike van Riel <[email protected]>', $context);
 
         $this->assertInstanceOf(Author::class, $tag);
@@ -326,7 +322,6 @@ class StandardTagFactoryTest extends TestCase
         $tagFactory->addService($descriptionFactory, DescriptionFactory::class);
         $tagFactory->addService($typeResolver, TypeResolver::class);
 
-        /** @var Return_ $tag */
         $tag = $tagFactory->create('@return mixed', $context);
 
         $this->assertInstanceOf(Return_::class, $tag);
@@ -337,7 +332,6 @@ class StandardTagFactoryTest extends TestCase
     {
         $tagFactory = new StandardTagFactory(m::mock(FqsenResolver::class));
 
-        /** @var InvalidTag $tag */
         $tag = $tagFactory->create('@see $name some invalid tag');
 
         $this->assertInstanceOf(InvalidTag::class, $tag);