Improve and rewrite phpdoc parser

Author: SerafimArts

Diff for: .php-cs-fixer.php

@@ -12,5 +12,5 @@
             'syntax' => 'short',
         ],
     ])
-    ->setCacheFile(__DIR__ . '/vendor/.php-cs-fixer.cache')
+    ->setCacheFile(__DIR__ . '/vendor/.cache.php-cs-fixer')
     ->setFinder($files);

Diff for: README.md

@@ -7,28 +7,58 @@
 ---
 
 <p align="center">
-    <a href="https://packagist.org/packages/type-lang/phpdoc-parser"><img src="https://poser.pugx.org/type-lang/phpdoc-parser/require/php?style=for-the-badge" alt="PHP 8.1+"></a>
-    <a href="https://packagist.org/packages/type-lang/phpdoc-parser"><img src="https://poser.pugx.org/type-lang/phpdoc-parser/version?style=for-the-badge" alt="Latest Stable Version"></a>
-    <a href="https://packagist.org/packages/type-lang/phpdoc-parser"><img src="https://poser.pugx.org/type-lang/phpdoc-parser/v/unstable?style=for-the-badge" alt="Latest Unstable Version"></a>
-    <a href="https://raw.githubusercontent.com/php-type-language/phpdoc-parser/blob/master/LICENSE"><img src="https://poser.pugx.org/type-lang/phpdoc-parser/license?style=for-the-badge" alt="License MIT"></a>
+    <a href="https://packagist.org/packages/type-lang/phpdoc"><img src="https://poser.pugx.org/type-lang/phpdoc/require/php?style=for-the-badge" alt="PHP 8.1+"></a>
+    <a href="https://packagist.org/packages/type-lang/phpdoc"><img src="https://poser.pugx.org/type-lang/phpdoc/version?style=for-the-badge" alt="Latest Stable Version"></a>
+    <a href="https://packagist.org/packages/type-lang/phpdoc"><img src="https://poser.pugx.org/type-lang/phpdoc/v/unstable?style=for-the-badge" alt="Latest Unstable Version"></a>
+    <a href="https://raw.githubusercontent.com/php-type-language/phpdoc-parser/blob/master/LICENSE"><img src="https://poser.pugx.org/type-lang/phpdoc/license?style=for-the-badge" alt="License MIT"></a>
 </p>
 <p align="center">
     <a href="https://github.com/php-type-language/phpdoc-parser/actions"><img src="https://github.com/php-type-language/phpdoc-parser/workflows/tests/badge.svg"></a>
 </p>
 
 The PHP reference implementation for Type Language PhpDoc Parser.
 
-Read [documentation pages](https://docs.phpdoc.io) for more information.
+Read [documentation pages](https://phpdoc.io) for more information.
 
 ## Installation
 
 PhpDoc Generator 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
+$ composer require type-lang/phpdoc
 ```
 
 ## Quick Start
 
-TODO
+```php
+use TypeLang\PHPDoc\DocBlockFactory;
+
+$phpdoc = DocBlockFactory::createInstance()
+    ->create(<<<'PHP'
+        /**
+         * Example description.
+         *
+         * @param non-empty-string $foo Foo param.
+         * @param int<0, max> $bar Bar param.
+         *
+         * @return void Returns nothing.
+         */
+        PHP);
+
+echo $phpdoc->getDescription() . "\n";
+// Output: string("Example description.\n")
+
+foreach ($phpdoc->getTags() as $tag) {
+    echo $tag->getName() . ': '
+       . $tag->getDescription() . "\n";
+    // Output 3 lines:
+    //   param: Foo param.
+    //   param: Bar param.
+    //   return: Returns nothing.
+}
+```
+
+### Supported Tags
+
+

Diff for: composer.json

@@ -1,32 +1,32 @@
 {
-    "name": "type-lang/phpdoc-parser",
+    "name": "type-lang/phpdoc",
     "type": "library",
-    "description": "PHP Types Reader",
-    "keywords": ["language", "php", "reader", "phpdoc", "docblock"],
+    "description": "PHPDoc",
+    "keywords": ["language", "php", "phpdoc", "docblock", "tags", "dictionary"],
     "license": "MIT",
     "support": {
-        "source": "https://github.com/php-type-language/phpdoc-parser",
-        "issues": "https://github.com/php-type-language/phpdoc-parser/issues"
+        "source": "https://github.com/php-type-language/phpdoc",
+        "issues": "https://github.com/php-type-language/phpdoc/issues"
     },
     "require": {
         "php": "^8.1",
-        "psr/http-message": "^1.0|^2.0",
+        "composer/semver": "^2.0|^3.0",
         "type-lang/parser": "^1.0"
     },
     "autoload": {
         "psr-4": {
-            "TypeLang\\PhpDoc\\Parser\\": "src"
+            "TypeLang\\PHPDoc\\": "src"
         }
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.42",
         "phpunit/phpunit": "^10.5",
-        "rector/rector": "^0.18",
+        "rector/rector": "^1.0",
         "vimeo/psalm": "^5.18"
     },
     "autoload-dev": {
         "psr-4": {
-            "TypeLang\\PhpDoc\\Parser\\Tests\\": "tests"
+            "TypeLang\\PHPDoc\\Tests\\": "tests"
         }
     },
     "extra": {

Diff for: phpunit.xml

@@ -6,7 +6,7 @@
          stopOnFailure="false"
          processIsolation="false"
          bootstrap="vendor/autoload.php"
-         cacheDirectory="vendor/.phpunit.cache"
+         cacheDirectory="vendor/.cache.phpunit"
          backupStaticProperties="false"
 >
     <testsuites>

Diff for: psalm.xml

@@ -7,6 +7,7 @@
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+    cacheDirectory="vendor/.cache.psalm"
 >
     <projectFiles>
         <directory name="src" />

Diff for: rector.php

@@ -10,14 +10,14 @@
 use Rector\Config\RectorConfig;
 use Rector\EarlyReturn\Rector\Return_\ReturnBinaryOrToEarlyReturnRector;
 use Rector\Php80\Rector\Class_\ClassPropertyAssignToConstructorPromotionRector;
-use Rector\Php81\Rector\ClassConst\FinalizePublicClassConstantRector;
 use Rector\Php81\Rector\Property\ReadOnlyPropertyRector;
 use Rector\Set\ValueObject\LevelSetList;
 use Rector\Set\ValueObject\SetList;
 use Rector\TypeDeclaration\Rector\FunctionLike\AddReturnTypeDeclarationFromYieldsRector;
 
 return static function (RectorConfig $config): void {
     $config->paths([__DIR__ . '/src']);
+    $config->cacheDirectory(__DIR__ . '/vendor/.cache.rector');
 
     $config->sets([
         LevelSetList::UP_TO_PHP_81,
@@ -32,7 +32,6 @@
         ReadOnlyPropertyRector::class,
         CatchExceptionNameMatchingTypeRector::class,
         SplitDoubleAssignRector::class,
-        FinalizePublicClassConstantRector::class,
         FlipTypeControlToUseExclusiveTypeRector::class,
         ReturnBinaryOrToEarlyReturnRector::class,
         LocallyCalledStaticMethodToNonStaticRector::class,

Diff for: src/Description/DescriptionFactoryInterface.php

@@ -2,33 +2,33 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PhpDoc\Parser;
+namespace TypeLang\PHPDoc;
 
 use TypeLang\Parser\Node\SerializableInterface;
-use TypeLang\PhpDoc\Parser\DocBlock\Description;
-use TypeLang\PhpDoc\Parser\DocBlock\Tag\TagInterface;
-use TypeLang\PhpDoc\Parser\DocBlock\TagProvider;
-use TypeLang\PhpDoc\Parser\DocBlock\TagProviderInterface;
+use TypeLang\PHPDoc\Tag\Description\Description;
+use TypeLang\PHPDoc\Tag\Description\DescriptionInterface;
+use TypeLang\PHPDoc\Tag\TagInterface;
+use TypeLang\PHPDoc\Tag\TagProvider;
+use TypeLang\PHPDoc\Tag\TagProviderInterface;
 
-final class DocBlock implements TagProviderInterface, SerializableInterface
+/**
+ * @template-implements \IteratorAggregate<array-key, TagInterface>
+ */
+final class DocBlock implements
+    TagProviderInterface,
+    SerializableInterface,
+    \IteratorAggregate
 {
-    use TagProvider {
-        getIterator as private getTagProviderIterator;
-    }
+    use TagProvider;
 
     /**
-     * @param iterable<array-key, TagInterface> $tags
+     * @param iterable<TagInterface> $tags
      */
     public function __construct(
-        private readonly Description $description = new Description(),
+        private readonly DescriptionInterface $description = new Description(),
         iterable $tags = [],
     ) {
-        $this->initializeTags($tags);
-    }
-
-    public function getDescription(): Description
-    {
-        return $this->description;
+        $this->bootTagProvider($tags);
     }
 
     /**
@@ -67,10 +67,4 @@ public function jsonSerialize(): array
     {
         return $this->toArray();
     }
-
-    public function getIterator(): \Traversable
-    {
-        yield from $this->description;
-        yield from $this->getTagProviderIterator();
-    }
 }