Make description factory optional for tag factories

Author: Kirill Nesmeyanov

src/DocBlock.php

@@ -11,7 +11,9 @@
 
 final class DocBlock implements TagProviderInterface
 {
-    use TagProvider;
+    use TagProvider {
+        getIterator as private getTagProviderIterator;
+    }
 
     /**
      * @param iterable<array-key, TagInterface> $tags
@@ -27,4 +29,10 @@ public function getDescription(): Description
     {
         return $this->description;
     }
+
+    public function getIterator(): \Traversable
+    {
+        yield from $this->description;
+        yield from $this->getTagProviderIterator();
+    }
 }

src/DocBlock/Description.php

@@ -20,7 +20,7 @@ public function __construct(
         $this->initializeTags($tags);
     }
 
-    public static function fromNonTagged(string $body): self
+    public static function create(string $body): self
     {
         return new self($body);
     }

src/DocBlock/StandardTagFactory.php

@@ -8,13 +8,14 @@
 use TypeLang\PhpDocParser\DocBlock\Tag\GenericTag;
 use TypeLang\PhpDocParser\DocBlock\Tag\InvalidTag;
 use TypeLang\PhpDocParser\DocBlock\Tag\InvalidTypedTag;
+use TypeLang\PhpDocParser\DocBlock\Tag\TagFactory;
 use TypeLang\PhpDocParser\DocBlock\Tag\TagInterface;
 use TypeLang\PhpDocParser\Exception\InvalidTagVariableNameException;
 
 /**
- * @template-implements TagFactoryInterface<TagInterface>
+ * @template-extends TagFactory<TagInterface>
  */
-final class StandardTagFactory implements TagFactoryInterface
+final class StandardTagFactory extends TagFactory
 {
     private readonly TagNameExtractor $parts;
 
@@ -48,6 +49,8 @@ public function __construct(
         foreach ($factories as $name => $factory) {
             $this->add($factory, $name);
         }
+
+        parent::__construct();
     }
 
     /**
@@ -84,17 +87,15 @@ public function create(string $tag): TagInterface
                 return $factory->create($body);
             } catch (InvalidTagVariableNameException $e) {
                 $type = $e->getType();
-                $body = Description::fromNonTagged(
-                    body: \substr($body, $e->getTypeOffset()),
-                );
+                $body = $this->createDescription(\substr($body, $e->getTypeOffset()));
 
                 if ($type === null) {
                     return new InvalidTag($name, $body);
                 }
 
                 return new InvalidTypedTag($name, $type, $body);
             } catch (\InvalidArgumentException) {
-                return new InvalidTag($name, Description::fromNonTagged($body));
+                return new InvalidTag($name, $this->createDescription($body));
             }
         }
 
@@ -104,7 +105,7 @@ public function create(string $tag): TagInterface
             return new GenericTag($name);
         }
 
-        return new GenericTag($name, Description::fromNonTagged($body));
+        return new GenericTag($name, $this->createDescription($body));
     }
 
     private function getFactory(string $tag): ?TagFactoryInterface

src/DocBlock/Tag/CommonTagFactory.php

@@ -15,11 +15,10 @@ final class CommonTagFactory extends TagFactory
 {
     /**
      * @param class-string<TTag> $class
-     * @param DescriptionFactoryInterface $descriptions
      */
     public function __construct(
         private readonly string $class,
-        DescriptionFactoryInterface $descriptions,
+        ?DescriptionFactoryInterface $descriptions = null,
     ) {
         parent::__construct($descriptions);
     }
@@ -29,7 +28,7 @@ public function create(string $tag): Tag
         try {
             /** @psalm-suppress UnsafeInstantiation */
             return new ($this->class)(
-                description: $this->extractDescription($tag),
+                description: $this->createDescription($tag),
             );
         } catch (\Throwable $e) {
             throw InvalidTagException::fromException($e);

src/DocBlock/Tag/CommonTypedTagFactory.php

@@ -20,7 +20,7 @@ final class CommonTypedTagFactory extends TypedTagFactory
     public function __construct(
         private readonly string $class,
         ParserInterface $parser,
-        DescriptionFactoryInterface $descriptions,
+        ?DescriptionFactoryInterface $descriptions = null,
     ) {
         parent::__construct($parser, $descriptions);
     }
@@ -33,7 +33,7 @@ public function create(string $tag): TypedTag
             /** @psalm-suppress UnsafeInstantiation */
             return new ($this->class)(
                 type: $type,
-                description: $this->extractDescription($description),
+                description: $this->createDescription($description),
             );
         } catch (\Throwable $e) {
             throw InvalidTagException::fromException($e);

src/DocBlock/Tag/CommonTypedTagWithNameFactory.php

@@ -24,7 +24,7 @@ final class CommonTypedTagWithNameFactory extends TypedTagFactory
     public function __construct(
         private readonly string $class,
         ParserInterface $parser,
-        DescriptionFactoryInterface $descriptions,
+        ?DescriptionFactoryInterface $descriptions = null,
     ) {
         $this->variables = new TagVariableExtractor();
 
@@ -48,7 +48,7 @@ public function create(string $tag): TypedTag
             return new ($this->class)(
                 variable: $variable,
                 type: $type,
-                description: $this->extractDescription($description),
+                description: $this->createDescription($description),
             );
         } catch (\Throwable $e) {
             throw InvalidTagException::fromException($e);

src/DocBlock/Tag/Tag.php

@@ -18,7 +18,7 @@ public function __construct(
         Description|string|null $description = null,
     ) {
         if (\is_string($description)) {
-            $description = Description::fromNonTagged($description);
+            $description = Description::create($description);
         }
 
         $this->description = $description;

src/DocBlock/Tag/TagFactory.php

@@ -6,6 +6,7 @@
 
 use TypeLang\PhpDocParser\DocBlock\Description;
 use TypeLang\PhpDocParser\DocBlock\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\DocBlock\Tag\TagInterface as TReturn;
 use TypeLang\PhpDocParser\DocBlock\TagFactoryInterface;
 
 /**
@@ -16,15 +17,30 @@
 abstract class TagFactory implements TagFactoryInterface
 {
     public function __construct(
-        protected readonly DescriptionFactoryInterface $descriptions,
+        protected ?DescriptionFactoryInterface $descriptions = null,
     ) {}
 
-    protected function extractDescription(?string $description): ?Description
+    protected function createDescription(?string $description): ?Description
     {
         if ($description !== null) {
-            return $this->descriptions->create($description);
+            return $this->descriptions?->create($description)
+                ?? Description::create($description)
+            ;
         }
 
         return null;
     }
+
+    public function withDescriptionFactory(?DescriptionFactoryInterface $factory): self
+    {
+        $self = clone $this;
+        $self->descriptions = $factory;
+
+        return $self;
+    }
+
+    public function getDescriptionFactory(): ?DescriptionFactoryInterface
+    {
+        return $this->descriptions;
+    }
 }

src/DocBlock/Tag/TypedTagFactory.php

@@ -19,7 +19,7 @@ abstract class TypedTagFactory extends TagFactory
 
     public function __construct(
         ParserInterface $parser,
-        DescriptionFactoryInterface $descriptions,
+        ?DescriptionFactoryInterface $descriptions = null,
     ) {
         $this->types = new TagTypeExtractor($parser);
 

src/DocBlock/TagFactoryInterface.php

@@ -20,4 +20,14 @@ interface TagFactoryInterface
      * @return TReturn|InvalidTagInterface A new tag object.
      */
     public function create(string $tag): TagInterface;
+
+    /**
+     * @psalm-immutable
+     */
+    public function withDescriptionFactory(?DescriptionFactoryInterface $factory): self;
+
+    /**
+     * @psalm-immutable
+     */
+    public function getDescriptionFactory(): ?DescriptionFactoryInterface;
 }