Support multiple line descriptions for all tags

Author: mglaman

src/Parser/PhpDocParser.php

@@ -60,8 +60,38 @@ private function parseChild(TokenIterator $tokens): Ast\PhpDoc\PhpDocChildNode
 
 	private function parseText(TokenIterator $tokens): Ast\PhpDoc\PhpDocTextNode
 	{
-		$text = $tokens->joinUntil(Lexer::TOKEN_PHPDOC_EOL, Lexer::TOKEN_CLOSE_PHPDOC, Lexer::TOKEN_END);
-		$text = rtrim($text, " \t"); // the trimmed characters MUST match Lexer::TOKEN_HORIZONTAL_WS
+		$text = '';
+		while (true) {
+			// If we received a Lexer::TOKEN_PHPDOC_EOL, exit early to prevent
+			// them from being processed.
+			if ($tokens->currentTokenType() === Lexer::TOKEN_PHPDOC_EOL) {
+				break;
+			}
+			$text .= $tokens->joinUntil(Lexer::TOKEN_PHPDOC_EOL, Lexer::TOKEN_CLOSE_PHPDOC, Lexer::TOKEN_END);
+			$text = rtrim($text, " \t");
+
+			// If we joined until TOKEN_PHPDOC_EOL, peak at the next tokens to see
+			// if we have a multiline string to join.
+			if ($tokens->currentTokenType() !== Lexer::TOKEN_PHPDOC_EOL) {
+				break;
+			}
+
+			// Peek at the next token to determine if it is more text that needs
+			// to be combined.
+			$tokens->pushSavePoint();
+			$tokens->next();
+			if ($tokens->currentTokenType() === Lexer::TOKEN_PHPDOC_EOL) {
+				$tokens->next();
+			}
+			if ($tokens->currentTokenType() !== Lexer::TOKEN_IDENTIFIER) {
+				$tokens->rollback();
+				break;
+			}
+
+			// There's more text on a new line, ensure spacing.
+			$text .= ' ';
+		}
+		$text = trim($text, " \t");
 
 		return new Ast\PhpDoc\PhpDocTextNode($text);
 	}
@@ -165,18 +195,7 @@ private function parseThrowsTagValue(TokenIterator $tokens): Ast\PhpDoc\ThrowsTa
 
 	private function parseDeprecatedTagValue(TokenIterator $tokens): Ast\PhpDoc\DeprecatedTagValueNode
 	{
-		$description = '';
-		while ($tokens->currentTokenType() !== Lexer::TOKEN_CLOSE_PHPDOC) {
-			$description .= $tokens->joinUntil(Lexer::TOKEN_PHPDOC_EOL, Lexer::TOKEN_CLOSE_PHPDOC, Lexer::TOKEN_END);
-			$description = rtrim($description, " \t");
-			if ($tokens->currentTokenType() !== Lexer::TOKEN_PHPDOC_EOL) {
-				break;
-			}
-			// There's more text on a new line, ensure spacing.
-			$description .= ' ';
-			$tokens->next();
-		}
-		$description = rtrim($description, " \t");
+		$description = $this->parseOptionalDescription($tokens);
 		return new Ast\PhpDoc\DeprecatedTagValueNode($description);
 	}
 

tests/PHPStan/Parser/PhpDocParserTest.php

@@ -992,6 +992,41 @@ public function provideDeprecatedTagsData(): \Iterator
 				),
 			]),
 		];
+		yield [
+			'OK with two simple description with break',
+			'/** @deprecated text first 
+        *
+        * @deprecated text second 
+        */',
+			new PhpDocNode([
+				new PhpDocTagNode(
+					'@deprecated',
+					new DeprecatedTagValueNode('text first')
+				),
+				new PhpDocTextNode(''),
+				new PhpDocTagNode(
+					'@deprecated',
+					new DeprecatedTagValueNode('text second')
+				),
+			]),
+		];
+
+		yield [
+			'OK with two simple description without break',
+			'/** @deprecated text first 
+        * @deprecated text second 
+        */',
+			new PhpDocNode([
+				new PhpDocTagNode(
+					'@deprecated',
+					new DeprecatedTagValueNode('text first')
+				),
+				new PhpDocTagNode(
+					'@deprecated',
+					new DeprecatedTagValueNode('text second')
+				),
+			]),
+		];
 
 		yield [
 			'OK with long descriptions',
@@ -1541,10 +1576,9 @@ public function provideMultiLinePhpDocData(): array
 							new IdentifierTypeNode('Foo'),
 							false,
 							'$foo',
-							'1st multi world description'
+							'1st multi world description some text in the middle'
 						)
 					),
-					new PhpDocTextNode('some text in the middle'),
 					new PhpDocTagNode(
 						'@param',
 						new ParamTagValueNode(
@@ -1561,15 +1595,16 @@ public function provideMultiLinePhpDocData(): array
 				'/**
 				  *
 				  *
-				  * @param Foo $foo 1st multi world description
+				  * @param Foo $foo 1st multi world description with empty lines
 				  *
 				  *
 				  * some text in the middle
 				  *
 				  *
-				  * @param Bar $bar 2nd multi world description
+				  * @param Bar $bar 2nd multi world description with empty lines
 				  *
 				  *
+				  * test
 				  */',
 				new PhpDocNode([
 					new PhpDocTextNode(''),
@@ -1580,7 +1615,7 @@ public function provideMultiLinePhpDocData(): array
 							new IdentifierTypeNode('Foo'),
 							false,
 							'$foo',
-							'1st multi world description'
+							'1st multi world description with empty lines'
 						)
 					),
 					new PhpDocTextNode(''),
@@ -1594,11 +1629,12 @@ public function provideMultiLinePhpDocData(): array
 							new IdentifierTypeNode('Bar'),
 							false,
 							'$bar',
-							'2nd multi world description'
+							'2nd multi world description with empty lines'
 						)
 					),
 					new PhpDocTextNode(''),
 					new PhpDocTextNode(''),
+					new PhpDocTextNode('test'),
 				]),
 			],
 			[