Merge pull request #444 from tmdk/fix/continuation-lines-with-star

Fix parsing of tag descriptions with continuation lines starting with *

Author: jaapio

src/DocBlock/Tags/Factory/AbstractPHPStanFactory.php

@@ -25,9 +25,10 @@
 use PHPStan\PhpDocParser\ParserConfig;
 use RuntimeException;
 
-use function ltrim;
 use function property_exists;
 use function rtrim;
+use function str_replace;
+use function trim;
 
 /**
  * Factory class creating tags using phpstan's parser
@@ -61,7 +62,7 @@ public function __construct(PHPStanFactory ...$factories)
     public function create(string $tagLine, ?TypeContext $context = null): Tag
     {
         try {
-            $tokens = $this->tokenizeLine($tagLine . "\n");
+            $tokens = $this->tokenizeLine($tagLine);
             $ast = $this->parser->parseTag($tokens);
             if (property_exists($ast->value, 'description') === true) {
                 $ast->value->setAttribute(
@@ -104,20 +105,20 @@ public function create(string $tagLine, ?TypeContext $context = null): Tag
      */
     private function tokenizeLine(string $tagLine): TokenIterator
     {
-        $tokens = $this->lexer->tokenize($tagLine);
+        // Prefix continuation lines with "* ", which is consumed by the phpstan parser as TOKEN_PHPDOC_EOL.
+        $tagLine = str_replace("\n", "\n* ", $tagLine);
+        $tokens = $this->lexer->tokenize($tagLine . "\n");
         $fixed = [];
         foreach ($tokens as $token) {
-            if (($token[1] === Lexer::TOKEN_PHPDOC_EOL) && rtrim($token[0], " \t") !== $token[0]) {
+            if ($token[Lexer::TYPE_OFFSET] === Lexer::TOKEN_PHPDOC_EOL) {
+                // Strip "* " prefix (and other horizontal whitespace) again so it doesn't and up in the
+                // description when we joinUntil() in create().
                 $fixed[] = [
-                    rtrim($token[Lexer::VALUE_OFFSET], " \t"),
-                    Lexer::TOKEN_PHPDOC_EOL,
-                    $token[2] ?? 0,
-                ];
-                $fixed[] = [
-                    ltrim($token[Lexer::VALUE_OFFSET], "\n\r"),
-                    Lexer::TOKEN_HORIZONTAL_WS,
-                    ($token[2] ?? 0) + 1,
+                    Lexer::VALUE_OFFSET => trim($token[Lexer::VALUE_OFFSET], "* \t"),
+                    Lexer::TYPE_OFFSET => $token[Lexer::TYPE_OFFSET],
+                    Lexer::LINE_OFFSET => $token[Lexer::LINE_OFFSET] ?? 0,
                 ];
+
                 continue;
             }
 

tests/integration/InterpretingDocBlocksTest.php

@@ -489,4 +489,43 @@ public function testParamTagDescriptionIsCorrectly(): void
         self::assertSame('Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas varius, tellus in cursus
 dictum, justo odio sagittis velit, id iaculis mi dui id nisi.', (string) $paramTags->getDescription());
     }
+
+    public function testParamBlockDescriptionPreservesStarContinuationLines(): void
+    {
+        $docComment = <<<DOC
+/**
+ * @param array \$foo {
+ *     Description of foo.
+ *
+ *     @type string \$bar Description of bar with
+ *                       * a list
+ *                       * spanning *multiple* lines
+ * }
+ */
+DOC;
+
+        $factory = DocBlockFactory::createInstance();
+        $docblock = $factory->create($docComment);
+
+        self::assertEquals(
+            [
+                new Param(
+                    'foo',
+                    new Array_(),
+                    false,
+                    new Description(<<<'DESCRIPTION'
+{
+    Description of foo.
+
+    @type string $bar Description of bar with
+                      * a list
+                      * spanning *multiple* lines
+}
+DESCRIPTION
+                    ),
+                ),
+            ],
+            $docblock->getTags()
+        );
+    }
 }