Remove unused interfaces

Author: SerafimArts

README.md

@@ -16,6 +16,151 @@
 
 The PHP reference implementation for Type Language PhpDoc Parser.
 
-## Resources
+Read [documentation pages](https://phpdoc.io) for more information.
 
-- [Documentation](https://phpdoc.io)
+## Installation
+
+Type Language PHPDoc Parser is available as Composer repository and can
+be installed using the following command in a root of your project:
+
+```sh
+$ composer require type-lang/phpdoc-parser
+```
+
+## Quick Start
+
+```php
+$parser = new \TypeLang\PHPDoc\Parser();
+$result = $parser->parse(<<<'PHPDOC'
+    /**
+     * Example description {@see some} and blah-blah-blah.
+     *
+     * @Example\Annotation("foo")
+     * @return array<non-empty-string, TypeStatement>
+     * @throws \Throwable
+     */
+    PHPDOC);
+
+var_dump($result);
+```
+
+**Expected Output:**
+```
+TypeLang\PHPDoc\DocBlock {
+  -description: TypeLang\PHPDoc\Tag\Description\Description {
+    -template: "Example description %1$s and blah-blah-blah."
+    -tags: array:1 [
+      0 => TypeLang\PHPDoc\Tag\Tag {
+        #description: TypeLang\PHPDoc\Tag\Description\Description {
+          -template: "some"
+          -tags: []
+        }
+        #name: "see"
+      }
+    ]
+  }
+  -tags: array:3 [
+    0 => TypeLang\PHPDoc\Tag\Tag {
+      #description: TypeLang\PHPDoc\Tag\Description\Description {
+        -template: "("foo")"
+        -tags: []
+      }
+      #name: "Example\Annotation"
+    }
+    1 => TypeLang\PHPDoc\Tag\Tag {
+      #description: TypeLang\PHPDoc\Tag\Description\Description {
+        -template: "array<non-empty-string, TypeStatement>"
+        -tags: []
+      }
+      #name: "return"
+    }
+    2 => TypeLang\PHPDoc\Tag\Tag {
+      #description: TypeLang\PHPDoc\Tag\Description\Description {
+        -template: "\Throwable"
+        -tags: []
+      }
+      #name: "throws"
+    }
+  ]
+}
+```
+
+### Structural Elements
+
+**DocBlock**
+
+DocBlock is a representation of the comment object.
+
+```php
+/**                                 |
+ * Hello world                      | ← DocBlock's description.
+ *                                  |
+ * @param int $example              | ← DocBlock's tag #1.
+ * @throws \Throwable Description   | ← DocBlock's tag #2.
+ */                                 |
+```
+
+- `getDescription()` ― Provides a `Description` object.
+- `getTags()` ― Provides a list of `Tag` objects.
+
+```php
+/** @template-implements \Traversable<array-key, Tag> */
+class DocBlock implements \Traversable
+{
+    public function getDescription(): Description;
+    
+    /** @return list<Tag> */
+    public function getTags(): array;
+}
+```
+
+**Description**
+
+Description is a representation of the description object which may contain
+other tags.
+
+```php
+/**
+               ↓↓↓↓↓↓↓↓↓↓↓                         | ← This is a nested tag of the description.
+ * Hello world {@see some} and blah-blah-blah.     |
+   ↑↑↑↑↑↑↑↑↑↑↑             ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑     | ← This is part of the template.
+ */
+```
+
+- `getTemplate()` ― Provides a sprintf-formatted template string of the description.
+- `getTags()` ― Provides a list of `Tag` objects.
+
+```php
+/** @template-implements \Traversable<array-key, Tag> */
+class Description implements \Traversable, \Stringable
+{
+    public function getTemplate(): string;
+
+    /** @return list<Tag> */
+    public function getTags(): array;
+}
+```
+
+**Tag**
+
+A Tag represents a name (ID) and its contents.
+
+```php
+/**
+    ↓↓↓↓↓↓                                 | ← This is a tag name.
+ * @throws \Throwable An error occurred.   |
+           ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑   | ← This is tag description.
+ */
+```
+
+- `getName()` ― Provides a tag's name (ID).
+- `getDescription()` ― Provides an optional description of the tag.
+
+```php
+class Tag implements \Stringable
+{
+    public function getName(): string;
+
+    public function getDescription(): ?Description;
+}
+```

src/DocBlock.php

@@ -4,26 +4,30 @@
 
 namespace TypeLang\PHPDoc;
 
-use TypeLang\PHPDoc\Tag\Description\Description;
-use TypeLang\PHPDoc\Tag\Description\DescriptionInterface;
-use TypeLang\PHPDoc\Tag\TagInterface;
+use TypeLang\PHPDoc\Tag\Description;
+use TypeLang\PHPDoc\Tag\Tag;
 use TypeLang\PHPDoc\Tag\TagProvider;
 use TypeLang\PHPDoc\Tag\TagProviderInterface;
 
 /**
- * @template-implements \IteratorAggregate<array-key, TagInterface>
+ * @template-implements \IteratorAggregate<array-key, Tag>
  */
 final class DocBlock implements TagProviderInterface, \IteratorAggregate
 {
     use TagProvider;
 
     /**
-     * @param iterable<array-key, TagInterface> $tags
+     * @param iterable<array-key, Tag> $tags
      */
     public function __construct(
-        private readonly DescriptionInterface $description = new Description(),
+        private readonly Description $description = new Description(),
         iterable $tags = [],
     ) {
         $this->bootTagProvider($tags);
     }
+
+    public function getDescription(): Description
+    {
+        return $this->description;
+    }
 }

src/Parser/Comment/CommentParserInterface.php

@@ -7,9 +7,6 @@
 /**
  * This interface is responsible for reading significant
  * sections of the DocBlock comment.
- *
- * @internal This is an internal library interface, please do not use it in your code.
- * @psalm-internal TypeLang\PHPDoc
  */
 interface CommentParserInterface
 {

src/Parser/Comment/LexerAwareCommentParser.php

@@ -17,9 +17,6 @@
 /**
  * This class is responsible for reading significant
  * sections of the DocBlock comment.
- *
- * @internal This is an internal library class, please do not use it in your code.
- * @psalm-internal TypeLang\PHPDoc
  */
 final class LexerAwareCommentParser implements CommentParserInterface
 {

src/Parser/Description/DescriptionParser.php

@@ -5,12 +5,11 @@
 namespace TypeLang\PHPDoc\Parser\Description;
 
 use TypeLang\PHPDoc\Parser\Tag\TagParserInterface;
-use TypeLang\PHPDoc\Tag\Description\Description;
-use TypeLang\PHPDoc\Tag\Description\DescriptionInterface;
+use TypeLang\PHPDoc\Tag\Description;
 
 abstract class DescriptionParser implements DescriptionParserInterface
 {
-    public function parse(string $description, TagParserInterface $parser = null): DescriptionInterface
+    public function parse(string $description, TagParserInterface $parser = null): Description
     {
         if ($parser === null || $description === '') {
             return new Description($description);
@@ -19,7 +18,7 @@ public function parse(string $description, TagParserInterface $parser = null): D
         return $this->doParseDescription($description, $parser);
     }
 
-    private function doParseDescription(string $description, TagParserInterface $parser): DescriptionInterface
+    private function doParseDescription(string $description, TagParserInterface $parser): Description
     {
         $tags = [];
         $tagIdentifier = 0;

src/Parser/Description/DescriptionParserInterface.php

@@ -5,7 +5,7 @@
 namespace TypeLang\PHPDoc\Parser\Description;
 
 use TypeLang\PHPDoc\Parser\Tag\TagParserInterface;
-use TypeLang\PHPDoc\Tag\Description\DescriptionInterface;
+use TypeLang\PHPDoc\Tag\Description;
 
 interface DescriptionParserInterface
 {
@@ -26,5 +26,5 @@ interface DescriptionParserInterface
      * // }
      * ```
      */
-    public function parse(string $description, TagParserInterface $parser = null): DescriptionInterface;
+    public function parse(string $description, TagParserInterface $parser = null): Description;
 }

src/Parser/SourceMap.php

@@ -4,6 +4,10 @@
 
 namespace TypeLang\PHPDoc\Parser;
 
+/**
+ * @internal This is an internal library class, please do not use it in your code.
+ * @psalm-internal TypeLang\PHPDoc
+ */
 final class SourceMap
 {
     /**

src/Parser/Tag/TagParser.php

@@ -7,7 +7,6 @@
 use TypeLang\PHPDoc\Exception\InvalidTagNameException;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 use TypeLang\PHPDoc\Tag\Tag;
-use TypeLang\PHPDoc\Tag\TagInterface;
 
 final class TagParser implements TagParserInterface
 {
@@ -73,7 +72,7 @@ private function getTagParts(string $content): array
     /**
      * @throws InvalidTagNameException
      */
-    public function parse(string $tag, DescriptionParserInterface $parser = null): TagInterface
+    public function parse(string $tag, DescriptionParserInterface $parser = null): Tag
     {
         // Tag name like ["var", "example"] extracted from "@var example"
         [$name, $content] = $this->getTagParts($tag);

src/Parser/Tag/TagParserInterface.php

@@ -5,7 +5,7 @@
 namespace TypeLang\PHPDoc\Parser\Tag;
 
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
-use TypeLang\PHPDoc\Tag\TagInterface;
+use TypeLang\PHPDoc\Tag\Tag;
 
 interface TagParserInterface
 {
@@ -24,5 +24,5 @@ interface TagParserInterface
      * // }
      * ```
      */
-    public function parse(string $tag, DescriptionParserInterface $parser = null): TagInterface;
+    public function parse(string $tag, DescriptionParserInterface $parser = null): Tag;
 }

src/Tag/Description/Description.php renamed to src/Tag/Description.php

@@ -2,26 +2,26 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PHPDoc\Tag\Description;
-
-use TypeLang\PHPDoc\Tag\TagInterface;
-use TypeLang\PHPDoc\Tag\TagProvider;
-use TypeLang\PHPDoc\Tag\TagProviderInterface;
+namespace TypeLang\PHPDoc\Tag;
 
 /**
- * @template-implements \IteratorAggregate<array-key, TagInterface>
+ * @template-implements \IteratorAggregate<array-key, Tag>
  */
-final class Description implements DescriptionInterface, TagProviderInterface, \IteratorAggregate
+class Description implements \Stringable, TagProviderInterface, \IteratorAggregate
 {
     use TagProvider;
 
+    private readonly string $template;
+
     /**
-     * @param iterable<array-key, TagInterface> $tags
+     * @param iterable<array-key, Tag> $tags
      */
     public function __construct(
-        private readonly string|\Stringable $template = '',
+        string|\Stringable $template = '',
         iterable $tags = [],
     ) {
+        $this->template = (string) $template;
+
         $this->bootTagProvider($tags);
     }
 
@@ -49,7 +49,7 @@ public static function fromStringOrNull(string|\Stringable|null $description): ?
      * @api
      * @psalm-immutable
      */
-    public function getTemplate(): string|\Stringable
+    public function getTemplate(): string
     {
         return $this->template;
     }