Fix empty docblocks behaviour and optimize docblock analyze + split logic

Author: SerafimArts

libs/phpdoc/src/DocBlockParser.php

@@ -281,8 +281,12 @@ private function createTags(array $segments, string $docblock): array
     /**
      * @throws PhpDocExceptionInterface
      */
-    private function tryCreateDescription(Segment $segment, string $docblock): ?DescriptionInterface
+    private function tryCreateDescription(?Segment $segment, string $docblock): ?DescriptionInterface
     {
+        if ($segment === null) {
+            return null;
+        }
+
         try {
             return $this->descriptionParser->tryParse($segment->text);
         } catch (\Throwable $e) {

libs/phpdoc/src/Parser/DocBlockAnalyzer.php

@@ -8,11 +8,11 @@
 use TypeLang\PhpDoc\Parser\Splitter\SplitterInterface;
 
 /**
- * Groups the significant segments of a DocBlock comment into sections (a
- * description followed by tags) and builds the {@see SourceMap} for them.
+ * Groups the significant segments of a DocBlock comment into a leading
+ * description followed by tags, joining each tag with its continuation lines.
  *
- * It only slices and maps the comment: parsing the description and tag
- * contents is left to the caller.
+ * A line opening with "@" starts a new tag; any line before the first tag
+ * belongs to the description, and any non-tag line after a tag continues it.
  */
 final readonly class DocBlockAnalyzer
 {
@@ -22,35 +22,51 @@ public function __construct(
 
     public function analyze(string $docblock): RawDocBlock
     {
-        $buffer = '';
-        $currentOffset = 0;
-        $hasOffset = false;
+        /** @phpstan-ignore-next-line : Pre-allocate (invalid) segment in order to use it as a
+         *                              template in the future (speeding up object instantiation) */
+        $prototype = new Segment('');
+
+        /** @var list<Segment> $groups */
+        $groups = [];
 
-        /** @var list<Segment> $computedSegments */
-        $computedSegments = [];
+        $buffer = '';
+        $offset = 0;
 
         foreach ($this->splitter->split($docblock) as $segment) {
-            $segmentText = $segment->text;
+            // A tag opens a new group; the previous one is finished first.
+            if ($buffer !== '' && $segment->text[0] === '@') {
+                /** @phpstan-ignore-next-line : Allow external mutation */
+                $prototype->text = $buffer;
+                /** @phpstan-ignore-next-line : Allow external mutation */
+                $prototype->offset = $offset;
 
-            if ($segmentText[0] === '@') {
-                $computedSegments[] = new Segment($buffer, $currentOffset);
+                $groups[] = clone $prototype;
                 $buffer = '';
-                $currentOffset = $segment->offset;
-                $hasOffset = true;
-            } elseif (!$hasOffset) {
-                // Anchor the leading description at its first significant line.
-                $currentOffset = $segment->offset;
-                $hasOffset = true;
+            }
+
+            if ($buffer === '') {
+                $offset = $segment->offset;
             }
 
             $buffer .= $segment->text;
         }
 
-        $computedSegments[] = new Segment($buffer, $currentOffset);
+        if ($buffer !== '') {
+            /** @phpstan-ignore-next-line : Allow external mutation */
+            $prototype->text = $buffer;
+            /** @phpstan-ignore-next-line : Allow external mutation */
+            $prototype->offset = $offset;
+
+            $groups[] = clone $prototype;
+        }
+
+        // The leading group is the description unless it already is a tag.
+        $description = null;
+
+        if ($groups !== [] && $groups[0]->text[0] !== '@') {
+            $description = \array_shift($groups);
+        }
 
-        return new RawDocBlock(
-            description: \array_shift($computedSegments),
-            tags: $computedSegments,
-        );
+        return new RawDocBlock($description, $groups);
     }
 }

libs/phpdoc/src/Parser/RawDocBlock.php

@@ -9,7 +9,7 @@
 final readonly class RawDocBlock
 {
     public function __construct(
-        public Segment $description,
+        public ?Segment $description,
         /**
          * @var list<Segment>
          */

libs/phpdoc/src/Parser/Splitter/Segment.php

@@ -13,7 +13,10 @@
 final class Segment
 {
     public function __construct(
-        public string $text = '',
+        /**
+         * @var non-empty-string
+         */
+        public string $text,
         /**
          * @var int<0, max>
          */