[FEATURE] Consider deprecated doc comment tag (#17)

* [FEATURE] Consider deprecated doc comment tag If a deprecated doc comment tag is recognized, its content is returned in RST format. For example the following php comment: ```php /** * Any text in RST format * * @deprecated since v11, will be removed in v12. */ ``` will be transformed to the following RST block: ```rst Any text in RST format .. attention:: **Deprecated** since v11, will be removed in v12. ``` References: TYPO3-Documentation/TYPO3CMS-Reference-ViewHelper#38 * [TASK] Run PHP CS Fixer --------- Co-authored-by: Simon Praetorius <simon@praetorius.me>
TYPO3 · May 22, 2024 · 79abd48 · 79abd48
1 parent b3d40c1
commit 79abd48
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 2 deletions.
diff --git a/src/DocCommentParser.php b/src/DocCommentParser.php
@@ -20,23 +20,45 @@ class DocCommentParser
      * getTags() getTagValues() and getDescription() methods.
      *
      * @param string $docComment A doc comment as returned by the reflection getDocComment() method
+     * @return string The parsed doc comment.
      */
     public function parseDocComment(string $docComment): string
     {
         $parsedDocComment = '';
+        $deprecatedTag = '';
         $lines = explode(chr(10), $docComment);
         foreach ($lines as $line) {
             if ($this->isDocCommentTag($line)) {
+                // Check if the line contains @deprecated, handle it
+                if (stripos($line, '@deprecated') !== false) {
+                    $line = str_replace('@deprecated', '**Deprecated**', $line);
+                    $line = $this->parsedDocCommentLine($line);
+                    $deprecatedTag = '..  attention::' . chr(10) . '    ' . $line;
+                }
                 continue;
             }
-            $parsedDocComment .= preg_replace('/\\s*\\/?[\\\\*]*(.*)$/', '$1', $line) . chr(10);
+            $parsedDocComment .= $this->parsedDocCommentLine($line);
         }
-        $parsedDocComment = trim($parsedDocComment);
+        $parsedDocComment = trim($parsedDocComment, " \n\r\t\v\x00\/") . chr(10);
+
+        // Append the deprecated tag if present
+        if ($deprecatedTag) {
+            $parsedDocComment .= chr(10) . $deprecatedTag;
+        }
+
+        // TODO: Check whether the forward slash at the end is necessary.
+        $parsedDocComment .= '/';
+
         return $parsedDocComment;
     }
 
     private function isDocCommentTag(string $line): bool
     {
         return preg_match('/^\s*\*?\s*@/', $line) === 1;
     }
+
+    private function parsedDocCommentLine(string $line): string
+    {
+        return preg_replace('/\\s*\\/?[\\\\*]*(.*)$/', '$1', $line) . chr(10);
+    }
 }
diff --git a/tests/Unit/DocCommentParserTest.php b/tests/Unit/DocCommentParserTest.php
@@ -34,6 +34,30 @@ public function returnsDescriptionWithoutTags(): void
         self::assertEquals($expected, $result);
     }
 
+    /**
+     * @test
+     */
+    public function returnsDescriptionWithoutTagsExceptDeprecated(): void
+    {
+        $subject = new DocCommentParser();
+        $expected = implode(PHP_EOL, [
+            'Some Description',
+            '',
+            '..  attention::',
+            '     **Deprecated** since v11, will be removed in v12.',
+            '/',
+        ]);
+
+        $result = $subject->parseDocComment(implode(PHP_EOL, [
+            '/**',
+            ' * Some Description',
+            ' * @param string $someParam With some description',
+            ' * @deprecated since v11, will be removed in v12.',
+            ' */',
+        ]));
+        self::assertEquals($expected, $result);
+    }
+
     /**
      * @test
      */