Support deprecated tags

Author: mglaman

src/Ast/PhpDoc/DeprecatedTagValueNode.php

@@ -0,0 +1,22 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\PhpDocParser\Ast\PhpDoc;
+
+class DeprecatedTagValueNode implements PhpDocTagValueNode
+{
+
+	/** @var string (may be empty) */
+	public $description;
+
+	public function __construct(?string $description = null)
+	{
+		$this->description = $description;
+	}
+
+
+	public function __toString(): string
+	{
+		return $this->description ? trim($this->description) : '';
+	}
+
+}

src/Parser/PhpDocParser.php

@@ -99,6 +99,10 @@ public function parseTagValue(TokenIterator $tokens, string $tag): Ast\PhpDoc\Ph
 					$tagValue = $this->parseThrowsTagValue($tokens);
 					break;
 
+				case '@deprecated':
+					$tagValue = $this->parseDeprecatedTagValue($tokens);
+					break;
+
 				case '@property':
 				case '@property-read':
 				case '@property-write':
@@ -159,6 +163,12 @@ private function parseThrowsTagValue(TokenIterator $tokens): Ast\PhpDoc\ThrowsTa
 		return new Ast\PhpDoc\ThrowsTagValueNode($type, $description);
 	}
 
+	private function parseDeprecatedTagValue(TokenIterator $tokens): Ast\PhpDoc\DeprecatedTagValueNode
+	{
+		$description = $this->parseOptionalDescription($tokens, true);
+		return new Ast\PhpDoc\DeprecatedTagValueNode($description);
+	}
+
 
 	private function parsePropertyTagValue(TokenIterator $tokens): Ast\PhpDoc\PropertyTagValueNode
 	{

tests/PHPStan/Parser/PhpDocParserTest.php

@@ -15,6 +15,7 @@
 use PHPStan\PhpDocParser\Ast\PhpDoc\PropertyTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ThrowsTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\DeprecatedTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\VarTagValueNode;
 use PHPStan\PhpDocParser\Ast\Type\ArrayTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
@@ -43,6 +44,7 @@ protected function setUp()
 	 * @dataProvider provideVarTagsData
 	 * @dataProvider provideReturnTagsData
 	 * @dataProvider provideThrowsTagsData
+	 * @dataProvider provideDeprecatedTagsData
 	 * @dataProvider providePropertyTagsData
 	 * @dataProvider provideMethodTagsData
 	 * @dataProvider provideSingleLinePhpDocData
@@ -967,6 +969,47 @@ public function provideThrowsTagsData(): \Iterator
 		];
 	}
 
+	public function provideDeprecatedTagsData() :\Iterator
+  {
+      yield [
+        'OK with no description',
+        '/** @deprecated */',
+        new PhpDocNode([
+          new PhpDocTagNode(
+            '@deprecated',
+            new DeprecatedTagValueNode()
+          )
+        ]),
+      ];
+
+      yield [
+        'OK with simple description description',
+        '/** @deprecated text string */',
+        new PhpDocNode([
+          new PhpDocTagNode(
+            '@deprecated',
+            new DeprecatedTagValueNode('text string')
+          )
+        ]),
+      ];
+
+      yield [
+        'OK with long descriptions',
+        '/** @deprecated in Drupal 8.6.0 and will be removed before Drupal 9.0.0. In
+   *   Drupal 9 there will be no way to set the status and in Drupal 8 this
+   *   ability has been removed because mb_*() functions are supplied using
+   *   Symfony\'s polyfill. */',
+        new PhpDocNode([
+          new PhpDocTagNode(
+            '@deprecated',
+            new DeprecatedTagValueNode('in Drupal 8.6.0 and will be removed before Drupal 9.0.0. In')
+          ),
+          new PhpDocTextNode('Drupal 9 there will be no way to set the status and in Drupal 8 this'),
+          new PhpDocTextNode('ability has been removed because mb_*() functions are supplied using'),
+          new PhpDocTextNode('Symfony\'s polyfill.'),
+        ]),
+      ];
+  }
 
 	public function provideMethodTagsData(): \Iterator
 	{