Improve phpdoc parser readers

Author: Kirill Nesmeyanov

src/Description/DescriptionFactory.php

@@ -7,8 +7,9 @@
 use TypeLang\PhpDocParser\DocBlock\Description;
 use TypeLang\PhpDocParser\DocBlock\Tag\TagInterface;
 use TypeLang\PhpDocParser\DocBlock\TagFactoryInterface;
+use TypeLang\PhpDocParser\Exception\InvalidTagNameException;
 
-final class DescriptionFactory implements DescriptionFactoryInterface
+abstract class DescriptionFactory implements DescriptionFactoryInterface
 {
     /**
      * @param TagFactoryInterface<TagInterface> $tags
@@ -34,12 +35,17 @@ public function create(string $contents): Description
             }
 
             if (\str_starts_with($chunk, '@')) {
-                $tags[] = $this->tags->create($chunk);
-                $description .= $this->createTagDescriptionChunk(++$tagIdentifier);
+                try {
+                    $tags[] = $this->tags->create($chunk);
+                    $description .= $this->createDescriptionChunkPlaceholder(++$tagIdentifier);
+                } catch (InvalidTagNameException) {
+                    $description .= "{{$chunk}}";
+                }
+
                 continue;
             }
 
-            $description .= $this->formatDescriptionChunk($chunk);
+            $description .= $this->escapeDescriptionChunk($chunk);
         }
 
         return new Description($description, $tags);
@@ -50,18 +56,12 @@ public function create(string $contents): Description
      *
      * @return non-empty-string
      */
-    private function createTagDescriptionChunk(int $tagId): string
-    {
-        return "%{$tagId}\$s";
-    }
+    abstract protected function createDescriptionChunkPlaceholder(int $tagId): string;
 
     /**
      * @return ($chunk is non-empty-string ? non-empty-string : string)
      */
-    private function formatDescriptionChunk(string $chunk): string
-    {
-        return \str_replace('%', '%%', $chunk);
-    }
+    abstract protected function escapeDescriptionChunk(string $chunk): string;
 
     /**
      * @return list<non-empty-string>

src/Description/SprintfDescriptionFactory.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\Description;
+
+final class SprintfDescriptionFactory extends DescriptionFactory
+{
+    /**
+     * @param int<0, max> $tagId
+     *
+     * @return non-empty-string
+     */
+    protected function createDescriptionChunkPlaceholder(int $tagId): string
+    {
+        return "%{$tagId}\$s";
+    }
+
+    /**
+     * @return ($chunk is non-empty-string ? non-empty-string : string)
+     */
+    protected function escapeDescriptionChunk(string $chunk): string
+    {
+        return \str_replace('%', '%%', $chunk);
+    }
+}

src/DocBlock/Extractor/TagNameExtractor.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\Reader;
+
+use TypeLang\Parser\Node\Stmt\TypeStatement;
+use TypeLang\Parser\Parser;
+
+/**
+ * @template-extends Reader<TypeStatement>
+ */
+final class OptionalTypeReader extends Reader
+{
+    public function __construct(
+        private readonly Parser $parser,
+    ) {}
+
+    /**
+     * @return Sequence<TypeStatement>|null
+     */
+    public function read(string $content): ?Sequence
+    {
+        try {
+            $type = $this->parser->parse($content);
+        } catch (\Throwable) {
+            return null;
+        }
+
+        if ($type instanceof TypeStatement) {
+            $offset = $this->parser->lastProcessedTokenOffset;
+
+            return new Sequence($type, $offset);
+        }
+
+        return null;
+    }
+}