Merge pull request #909 from phpDocumentor/backport/1.x/pr-908

[1.x] [BUGFIX] Improve comment handling

Author: phpdoc-bot

packages/guides-restructured-text/src/RestructuredText/Parser/LineChecker.php

@@ -15,6 +15,8 @@
 
 use function in_array;
 use function mb_strlen;
+use function preg_match;
+use function trim;
 
 final class LineChecker
 {
@@ -74,4 +76,19 @@ public static function isSpecialLine(string $line, int $minimumLength = 2): stri
 
         return $letter;
     }
+
+    public static function isDirective(string $line): bool
+    {
+        return preg_match('/^\.\.\s+(\|(.+)\| |)([^\s]+)::( (.*)|)$/mUsi', $line) > 0;
+    }
+
+    public static function isLink(string $line): bool
+    {
+        return preg_match('/^\.\.\s+_(.+):.*$/mUsi', trim($line)) > 0;
+    }
+
+    public static function isAnnotation(string $line): bool
+    {
+        return preg_match('/^\.\.\s+\[([#a-zA-Z0-9]*)\]\s(.*)$$/mUsi', $line) > 0;
+    }
 }

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/AnnotationRule.php

@@ -22,6 +22,7 @@
 use phpDocumentor\Guides\RestructuredText\Parser\AnnotationUtility;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Buffer;
+use phpDocumentor\Guides\RestructuredText\Parser\LineChecker;
 use phpDocumentor\Guides\RestructuredText\Parser\LinesIterator;
 
 use function preg_match;
@@ -42,12 +43,7 @@ public function __construct(
 
     public function applies(BlockContext $blockContext): bool
     {
-        return $this->isAnnotation($blockContext->getDocumentIterator()->current());
-    }
-
-    private function isAnnotation(string $line): bool
-    {
-        return preg_match('/^\.\.\s+\[([#a-zA-Z0-9]*)\]\s(.*)$$/mUsi', $line) > 0;
+        return LineChecker::isAnnotation($blockContext->getDocumentIterator()->current());
     }
 
     public function apply(BlockContext $blockContext, CompoundNode|null $on = null): Node|null
@@ -66,7 +62,7 @@ public function apply(BlockContext $blockContext, CompoundNode|null $on = null):
             && LinesIterator::isEmptyLine($documentIterator->getNextLine()) === false
         ) {
             $documentIterator->next();
-            if ($this->isAnnotation($documentIterator->current())) {
+            if (LineChecker::isAnnotation($documentIterator->current())) {
                 $nodes[] = $this->createAnnotationNode($annotationKey, $buffer, $blockContext, $documentIterator, $name);
                 $openingLine = $documentIterator->current();
                 [$annotationKey, $content] = $this->analyzeOpeningLine($openingLine);

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/CommentRule.php

@@ -17,8 +17,9 @@
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Buffer;
+use phpDocumentor\Guides\RestructuredText\Parser\LineChecker;
 
-use function preg_match;
+use function str_starts_with;
 use function trim;
 
 /**
@@ -59,8 +60,27 @@ private function isCommentLine(string|null $line): bool
         return $this->isComment($line) || trim($line) === '' || $line[0] === ' ';
     }
 
+    /**
+     * Every explicit markup block which is not a valid markup construct is regarded as a comment.
+     */
     private function isComment(string $line): bool
     {
-        return trim($line) === '..' || preg_match('/^\.\.\s+[^:]*$/mUsi', $line) > 0;
+        if (trim($line) === '..') {
+            return true;
+        }
+
+        if (!str_starts_with($line, '.. ')) {
+            return false;
+        }
+
+        if (LineChecker::isDirective($line)) {
+            return false;
+        }
+
+        if (LineChecker::isLink($line)) {
+            return false;
+        }
+
+        return !LineChecker::isAnnotation($line);
     }
 }

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/DirectiveRule.php

@@ -22,6 +22,7 @@
 use phpDocumentor\Guides\RestructuredText\Parser\Buffer;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
+use phpDocumentor\Guides\RestructuredText\Parser\LineChecker;
 use phpDocumentor\Guides\RestructuredText\Parser\LinesIterator;
 use phpDocumentor\Guides\RestructuredText\Parser\UnindentStrategy;
 use Psr\Log\LoggerInterface;
@@ -69,12 +70,7 @@ private function registerDirective(DirectiveHandler $directive): void
 
     public function applies(BlockContext $blockContext): bool
     {
-        return $this->isDirective($blockContext->getDocumentIterator()->current());
-    }
-
-    private function isDirective(string $line): bool
-    {
-        return preg_match('/^\.\.\s+(\|(.+)\| |)([^\s]+)::( (.*)|)$/mUsi', $line) > 0;
+        return LineChecker::isDirective($blockContext->getDocumentIterator()->current());
     }
 
     public function apply(BlockContext $blockContext, CompoundNode|null $on = null): Node|null

tests/Integration/tests/comments/comment-ends-in-markup/expected/index.html

@@ -0,0 +1,29 @@
+<!-- content start -->
+    <div class="section" id="some-title">
+            <a id="nocomment"></a>
+            <h1>Some Title</h1>
+
+            <div class="admonition note">
+        <p>No comment!</p>
+</div>
+
+            <div class="section" id="another-title">
+            <a id="alsonoomment"></a>
+            <h2>Another title</h2>
+
+                <div class="footnote " id="footnote-1">
+    <div class="footnote-label">[1]</div>
+    <div class="footnote-content">Text of the first footnote.</div>
+</div>
+
+    <div class="footnote " id="footnote-2">
+    <div class="footnote-label">[2]</div>
+    <div class="footnote-content">Text of the second footnote.</div>
+</div>
+
+
+    </div>
+
+    </div>
+
+<!-- content end -->

tests/Integration/tests/comments/comment-ends-in-markup/input/index.rst

@@ -0,0 +1,17 @@
+..  _nocomment:
+
+Some Title
+==========
+
+..  Generated by https://example.com/
+..  note:: No comment!
+
+.. this is a commend
+..  _alsonoomment:
+
+Another title
+-------------
+
+.. this is a commend
+.. [#f1] Text of the first footnote.
+.. [#f2] Text of the second footnote.