Add basic docblocks support

Kirill Nesmeyanov · Kirill Nesmeyanov · commit ee0d8a52d55c · 2023-11-24T22:07:29.000+03:00
diff --git a/composer.json b/composer.json
@@ -10,6 +10,7 @@
     },
     "require": {
         "php": "^8.1",
+        "psr/http-message": "^1.0|^2.0",
         "type-lang/parser": "^1.0"
     },
     "autoload": {
diff --git a/src/Description/DescriptionFactory.php b/src/Description/DescriptionFactory.php
@@ -2,9 +2,11 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PhpDocParser\DocBlock;
+namespace TypeLang\PhpDocParser\Description;
 
+use TypeLang\PhpDocParser\DocBlock\Description;
 use TypeLang\PhpDocParser\DocBlock\Tag\TagInterface;
+use TypeLang\PhpDocParser\DocBlock\TagFactoryInterface;
 
 final class DescriptionFactory implements DescriptionFactoryInterface
 {
diff --git a/src/Description/DescriptionFactoryInterface.php b/src/Description/DescriptionFactoryInterface.php
@@ -2,7 +2,9 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PhpDocParser\DocBlock;
+namespace TypeLang\PhpDocParser\Description;
+
+use TypeLang\PhpDocParser\DocBlock\Description;
 
 interface DescriptionFactoryInterface
 {
diff --git a/src/DocBlock/Extractor/TagReferenceExtractor.php b/src/DocBlock/Extractor/TagReferenceExtractor.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\Extractor;
+
+use TypeLang\PhpDocParser\DocBlock\Reference\ReferenceInterface;
+use TypeLang\PhpDocParser\DocBlock\Reference\UriReference;
+
+final class TagReferenceExtractor
+{
+    public function extract(string $body): array
+    {
+        $description = \strpbrk($body, " \t\n\r\0\x0B");
+
+        if ($description === false) {
+            return [$this->parseReference($body), null];
+        }
+
+        $descriptionOffset = \strlen($body) - \strlen($description);
+
+        return [
+            $this->parseReference(\substr($body, 0, $descriptionOffset)),
+            \ltrim($description),
+        ];
+    }
+
+    private function parseReference(string $body): ReferenceInterface
+    {
+        return new UriReference($body);
+    }
+}
diff --git a/src/DocBlock/Reference/ReferenceInterface.php b/src/DocBlock/Reference/ReferenceInterface.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\Reference;
+
+interface ReferenceInterface extends \Stringable
+{
+    /**
+     * Returns string representation of the reference.
+     */
+    public function __toString(): string;
+}
diff --git a/src/DocBlock/Reference/UriReference.php b/src/DocBlock/Reference/UriReference.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\Reference;
+
+final class UriReference implements ReferenceInterface
+{
+    public function __construct(
+        private readonly string $uri,
+    ) {}
+
+    public function __toString(): string
+    {
+        return $this->uri;
+    }
+}
diff --git a/src/DocBlock/Tag/LinkTag.php b/src/DocBlock/Tag/LinkTag.php
@@ -4,13 +4,22 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
+use TypeLang\PhpDocParser\DocBlock\Reference\ReferenceInterface;
+
 /**
- * TODO Add url extraction: {@link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/link.html#link}
+ * @link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/link.html#link
  */
 final class LinkTag extends Tag
 {
-    public function __construct(\Stringable|string|null $description = null)
-    {
+    public function __construct(
+        private readonly ReferenceInterface $reference,
+        \Stringable|string|null $description = null,
+    ) {
         parent::__construct('link', $description);
     }
+
+    public function getReference(): ReferenceInterface
+    {
+        return $this->reference;
+    }
 }
diff --git a/src/DocBlock/Tag/SeeTag.php b/src/DocBlock/Tag/SeeTag.php
@@ -4,13 +4,22 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
+use TypeLang\PhpDocParser\DocBlock\Reference\ReferenceInterface;
+
 /**
- * TODO Add url/fqsen extraction: {@link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/see.html#see}
+ * @link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/see.html#see
  */
 final class SeeTag extends Tag
 {
-    public function __construct(\Stringable|string|null $description = null)
-    {
+    public function __construct(
+        private readonly ReferenceInterface $reference,
+        \Stringable|string|null $description = null,
+    ) {
         parent::__construct('see', $description);
     }
+
+    public function getReference(): ReferenceInterface
+    {
+        return $this->reference;
+    }
 }
diff --git a/src/DocBlock/TagFactory/CommonTagFactory.php b/src/DocBlock/TagFactory/CommonTagFactory.php
@@ -2,9 +2,10 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PhpDocParser\DocBlock\Tag;
+namespace TypeLang\PhpDocParser\DocBlock\TagFactory;
 
-use TypeLang\PhpDocParser\DocBlock\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\Description\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\DocBlock\Tag\Tag;
 use TypeLang\PhpDocParser\Exception\InvalidTagException;
 
 /**
diff --git a/src/DocBlock/TagFactory/CommonTypedTagFactory.php b/src/DocBlock/TagFactory/CommonTypedTagFactory.php
@@ -2,10 +2,12 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PhpDocParser\DocBlock\Tag;
+namespace TypeLang\PhpDocParser\DocBlock\TagFactory;
 
 use TypeLang\Parser\Parser;
-use TypeLang\PhpDocParser\DocBlock\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\Description\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\DocBlock\Tag\TypedTag;
+use TypeLang\PhpDocParser\DocBlock\TagFactory\TypedTagFactory;
 use TypeLang\PhpDocParser\Exception\InvalidTagException;
 
 /**
diff --git a/src/DocBlock/TagFactory/CommonTypedTagWithNameFactory.php b/src/DocBlock/TagFactory/CommonTypedTagWithNameFactory.php
@@ -2,11 +2,13 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PhpDocParser\DocBlock\Tag;
+namespace TypeLang\PhpDocParser\DocBlock\TagFactory;
 
 use TypeLang\Parser\Parser;
-use TypeLang\PhpDocParser\DocBlock\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\Description\DescriptionFactoryInterface;
 use TypeLang\PhpDocParser\DocBlock\Extractor\TagVariableExtractor;
+use TypeLang\PhpDocParser\DocBlock\Tag\TypedTag;
+use TypeLang\PhpDocParser\DocBlock\TagFactory\TypedTagFactory;
 use TypeLang\PhpDocParser\Exception\InvalidTagException;
 use TypeLang\PhpDocParser\Exception\InvalidTagVariableNameException;
 
diff --git a/src/DocBlock/TagFactory/LinkTagFactory.php b/src/DocBlock/TagFactory/LinkTagFactory.php
@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\TagFactory;
+
+
+use TypeLang\PhpDocParser\Description\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\DocBlock\Extractor\TagReferenceExtractor;
+use TypeLang\PhpDocParser\DocBlock\Tag\Tag;
+use TypeLang\PhpDocParser\Exception\InvalidTagException;
+
+/**
+ * @template TTag of Tag
+ * @template-extends TagFactory<TTag>
+ */
+final class LinkTagFactory extends TagFactory
+{
+    private readonly TagReferenceExtractor $references;
+
+    /**
+     * @param class-string<TTag> $class
+     */
+    public function __construct(
+        private readonly string $class,
+        ?DescriptionFactoryInterface $descriptions = null,
+    ) {
+        $this->references = new TagReferenceExtractor();
+
+        parent::__construct($descriptions);
+    }
+
+    public function create(string $tag): Tag
+    {
+        [$reference, $description] = $this->references->extract($tag);
+
+        try {
+            /** @psalm-suppress UnsafeInstantiation */
+            return new ($this->class)(
+                $reference,
+                description: $this->createDescription($description),
+            );
+        } catch (\Throwable $e) {
+            throw InvalidTagException::fromException($e);
+        }
+    }
+}
diff --git a/src/DocBlock/TagFactory/TagFactory.php b/src/DocBlock/TagFactory/TagFactory.php
@@ -2,10 +2,11 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PhpDocParser\DocBlock\Tag;
+namespace TypeLang\PhpDocParser\DocBlock\TagFactory;
 
 use TypeLang\PhpDocParser\DocBlock\Description;
-use TypeLang\PhpDocParser\DocBlock\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\Description\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\DocBlock\Tag\TagInterface;
 use TypeLang\PhpDocParser\DocBlock\TagFactoryInterface;
 
 /**
diff --git a/src/DocBlock/TagFactory/TypedTagFactory.php b/src/DocBlock/TagFactory/TypedTagFactory.php
@@ -2,11 +2,12 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PhpDocParser\DocBlock\Tag;
+namespace TypeLang\PhpDocParser\DocBlock\TagFactory;
 
 use TypeLang\Parser\Parser;
-use TypeLang\PhpDocParser\DocBlock\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\Description\DescriptionFactoryInterface;
 use TypeLang\PhpDocParser\DocBlock\Extractor\TagTypeExtractor;
+use TypeLang\PhpDocParser\DocBlock\Tag\TagInterface;
 
 /**
  * @template TReturn of TagInterface
diff --git a/src/DocBlock/TagFactoryInterface.php b/src/DocBlock/TagFactoryInterface.php
@@ -4,6 +4,7 @@
 
 namespace TypeLang\PhpDocParser\DocBlock;
 
+use TypeLang\PhpDocParser\Description\DescriptionFactoryInterface;
 use TypeLang\PhpDocParser\DocBlock\Tag\InvalidTagInterface;
 use TypeLang\PhpDocParser\DocBlock\Tag\TagInterface;
 
diff --git a/src/DocBlock/TagFactorySelector.php b/src/DocBlock/TagFactorySelector.php
@@ -8,14 +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\TagFactory\TagFactory;
 use TypeLang\PhpDocParser\DocBlock\Tag\TagInterface;
 use TypeLang\PhpDocParser\Exception\InvalidTagVariableNameException;
 
 /**
  * @template-extends TagFactory<TagInterface>
  */
-final class StandardTagFactory extends TagFactory
+final class TagFactorySelector extends TagFactory
 {
     private readonly TagNameExtractor $parts;
 
diff --git a/src/DocBlockFactory.php b/src/DocBlockFactory.php
@@ -6,12 +6,13 @@
 
 use TypeLang\Parser\Parser;
 use TypeLang\PhpDocParser\DocBlock\Description;
-use TypeLang\PhpDocParser\DocBlock\DescriptionFactory;
-use TypeLang\PhpDocParser\DocBlock\DescriptionFactoryInterface;
-use TypeLang\PhpDocParser\DocBlock\StandardTagFactory;
+use TypeLang\PhpDocParser\Description\DescriptionFactory;
+use TypeLang\PhpDocParser\Description\DescriptionFactoryInterface;
+use TypeLang\PhpDocParser\DocBlock\TagFactory\LinkTagFactory;
+use TypeLang\PhpDocParser\DocBlock\TagFactorySelector;
 use TypeLang\PhpDocParser\DocBlock\Tag\ApiTag;
 use TypeLang\PhpDocParser\DocBlock\Tag\AuthorTag;
-use TypeLang\PhpDocParser\DocBlock\Tag\CommonTypedTagWithNameFactory;
+use TypeLang\PhpDocParser\DocBlock\TagFactory\CommonTypedTagWithNameFactory;
 use TypeLang\PhpDocParser\DocBlock\Tag\ExampleTag;
 use TypeLang\PhpDocParser\DocBlock\Tag\FilesourceTag;
 use TypeLang\PhpDocParser\DocBlock\Tag\GlobalTag;
@@ -23,8 +24,8 @@
 use TypeLang\PhpDocParser\DocBlock\Tag\CopyrightTag;
 use TypeLang\PhpDocParser\DocBlock\Tag\DeprecatedTag;
 use TypeLang\PhpDocParser\DocBlock\Tag\FinalTag;
-use TypeLang\PhpDocParser\DocBlock\Tag\CommonTagFactory;
-use TypeLang\PhpDocParser\DocBlock\Tag\CommonTypedTagFactory;
+use TypeLang\PhpDocParser\DocBlock\TagFactory\CommonTagFactory;
+use TypeLang\PhpDocParser\DocBlock\TagFactory\CommonTypedTagFactory;
 use TypeLang\PhpDocParser\DocBlock\Tag\ImmutableTag;
 use TypeLang\PhpDocParser\DocBlock\Tag\InheritDocTag;
 use TypeLang\PhpDocParser\DocBlock\Tag\InternalTag;
@@ -62,7 +63,7 @@ public function __construct(
 
     public static function createInstance(?Parser $parser = null): self
     {
-        $tags = new StandardTagFactory();
+        $tags = new TagFactorySelector();
 
         foreach (self::getStandardPrefixes() as $prefix) {
             $tags->addPrefix($prefix);
@@ -129,16 +130,17 @@ public static function getStandardTags(?Parser $parser = null): iterable
         yield 'inheritdoc' => new CommonTagFactory(InheritDocTag::class);
         yield 'internal' => new CommonTagFactory(InternalTag::class);
         yield 'license' => new CommonTagFactory(LicenseTag::class);
-        yield 'link' => new CommonTagFactory(LinkTag::class);
         yield 'method' => new CommonTagFactory(MethodTag::class);
         yield 'no-named-arguments' => new CommonTagFactory(NoNamedArgumentsTag::class);
-        yield 'see' => new CommonTagFactory(SeeTag::class);
         yield 'since' => new CommonTagFactory(SinceTag::class);
         yield 'source' => new CommonTagFactory(SourceTag::class);
         yield 'todo' => new CommonTagFactory(TodoTag::class);
         yield ['used-by', 'usedby'] => new CommonTagFactory(UsedByTag::class);
         yield 'uses' => new CommonTagFactory(UsesTag::class);
         yield 'version' => new CommonTagFactory(VersionTag::class);
+
+        yield 'see' => new LinkTagFactory(SeeTag::class);
+        yield 'link' => new LinkTagFactory(LinkTag::class);
     }
 
     public function create(#[Language('PHP')] string $docblock): DocBlock

Original file line number	Diff line number	Diff line change
`@@ -2,9 +2,11 @@`
`2`	`2`
`3`	`3`	`declare(strict_types=1);`
`4`	`4`
`5`		`-namespace TypeLang\PhpDocParser\DocBlock;`
	`5`	`+namespace TypeLang\PhpDocParser\Description;`
`6`	`6`
	`7`	`+use TypeLang\PhpDocParser\DocBlock\Description;`
`7`	`8`	`use TypeLang\PhpDocParser\DocBlock\Tag\TagInterface;`
	`9`	`+use TypeLang\PhpDocParser\DocBlock\TagFactoryInterface;`
`8`	`10`
`9`	`11`	`final class DescriptionFactory implements DescriptionFactoryInterface`
`10`	`12`	`{`
Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,9 @@`
`2`	`2`
`3`	`3`	`declare(strict_types=1);`
`4`	`4`
`5`		`-namespace TypeLang\PhpDocParser\DocBlock;`
	`5`	`+namespace TypeLang\PhpDocParser\Description;`
	`6`	`+`
	`7`	`+use TypeLang\PhpDocParser\DocBlock\Description;`
`6`	`8`
`7`	`9`	`interface DescriptionFactoryInterface`
`8`	`10`	`{`