Add docs

docs/contributing.rst

@@ -0,0 +1,12 @@
+Contributing
+============
+
+Contributions are welcome! If you would like to contribute to ReflectionDocBlock, please follow these guidelines:
+
+- Fork the repository and create your branch from ``main``.
+- Ensure your code follows the project's coding standards.
+- Write tests for your changes.
+- Submit a pull request with a clear description of your changes.
+
+For questions or discussions, please open an issue on GitHub.
+

docs/examples/01-interpreting-a-simple-docblock.php

@@ -0,0 +1,27 @@
+<?php
+require_once(__DIR__ . '/../../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlockFactory;
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * This is a Description. A Summary and Description are separated by either
+ * two subsequent newlines (thus a whiteline in between as can be seen in this
+ * example), or when the Summary ends with a dot (`.`) and some form of
+ * whitespace.
+ */
+DOCCOMMENT;
+
+$factory  = DocBlockFactory::createInstance();
+$docblock = $factory->create($docComment);
+
+// Should contain the first line of the DocBlock
+$summary = $docblock->getSummary();
+
+// Contains an object of type Description; you can either cast it to string or use
+// the render method to get a string representation of the Description.
+//
+// In subsequent examples we will be fiddling a bit more with the Description.
+$description = $docblock->getDescription();

docs/examples/02-interpreting-tags.php

@@ -0,0 +1,24 @@
+<?php
+require_once(__DIR__ . '/../../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlockFactory;
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * @see \phpDocumentor\Reflection\DocBlock\StandardTagFactory
+ */
+DOCCOMMENT;
+
+$factory  = DocBlockFactory::createInstance();
+$docblock = $factory->create($docComment);
+
+// You can check if a DocBlock has one or more see tags
+$hasSeeTag = $docblock->hasTag('see');
+
+// Or we can get a complete list of all tags
+$tags = $docblock->getTags();
+
+// But we can also grab all tags of a specific type, such as `see`
+$seeTags = $docblock->getTagsByName('see');

docs/examples/03-reconstituting-a-docblock.php

@@ -0,0 +1,27 @@
+<?php
+
+require_once(__DIR__ . '/../../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlock\Serializer;
+use phpDocumentor\Reflection\DocBlockFactory;
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * And here is an example of the description
+ * of a DocBlock that can span multiple lines.
+ *
+ * @see \phpDocumentor\Reflection\DocBlock\StandardTagFactory
+ */
+DOCCOMMENT;
+
+$factory  = DocBlockFactory::createInstance();
+$docblock = $factory->create($docComment);
+
+// Create the serializer that will reconstitute the DocBlock back to its original form.
+$serializer = new Serializer(0, '', true, null, null, PHP_EOL);
+
+// Reconstitution is performed by the `getDocComment()` method.
+$reconstitutedDocComment = $serializer->getDocComment($docblock);
+

docs/examples/04-adding-your-own-tag.php

@@ -0,0 +1,131 @@
+<?php
+/**
+ * In this example we demonstrate how you can add your own Tag using a Static Factory method in your Tag class.
+ */
+
+require_once(__DIR__ . '/../../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlock\Serializer;
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\DocBlockFactory;
+use phpDocumentor\Reflection\DocBlock\Description;
+use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\BaseTag;
+use phpDocumentor\Reflection\Types\Context;
+use Webmozart\Assert\Assert;
+
+/**
+ * An example of a custom tag called `my-tag` with an optional description.
+ *
+ * A Custom Tag is a class that can consist of two parts:
+ *
+ * 1. a method `create` that is a static factory for this class.
+ * 2. methods and properties that have this object act as an immutable Value Object representing a Tag instance.
+ *
+ * The static factory `create` is used to convert a tag line (without the tag name) into an instance of the
+ * same tag object with the right constructor parameters set. This method has a dynamic list of parameters so that you
+ * can inject various dependencies, see the method's DocBlock for more information.
+ *
+ * An object of this class, and its methods and properties, represent a single instance of that tag in your
+ * documentation in the form of a Value Object whose properties should not be changed after instantiation (it should be
+ * immutable).
+ *
+ * > Important: Tag classes that act as Factories using the `create` method should implement the Tag interface.
+ * > Instead, you could extend the abstract class BaseTag that already implements the Tag interface
+ */
+final class MyTag extends BaseTag
+{
+    /**
+     * A required property that is used by Formatters to reconstitute the complete tag line.
+     *
+     * @see Formatter
+     *
+     * @var string
+     */
+    protected string $name = 'my-tag';
+
+    /**
+     * The constructor for this Tag; this should contain all properties for this object.
+     *
+     * @param Description $description An example of how to add a Description to the tag; the Description is often
+     *                                 an optional variable so passing null is allowed in this instance (though you can
+     *                                 also construct an empty description object).
+     *
+     * @see BaseTag for the declaration of the description property and getDescription method.
+     */
+    public function __construct(Description $description = null)
+    {
+        $this->description = $description;
+    }
+
+    /**
+     * A static Factory that creates a new instance of the current Tag.
+     *
+     * In this example the MyTag tag can be created by passing a description text as $body. Because we have added
+     * a $descriptionFactory that is type-hinted as DescriptionFactory we can now construct a new Description object
+     * and pass that to the constructor.
+     *
+     * > You could directly instantiate a Description object here but that won't be parsed for inline tags and Types
+     * > won't be resolved. The DescriptionFactory will take care of those actions.
+     *
+     * The `create` method's interface states that this method only features a single parameter (`$body`) but the
+     * {@see TagFactory} will read the signature of this method and if it has more parameters then it will try
+     * to find declarations for it in the ServiceLocator of the TagFactory (see {@see TagFactory::$serviceLocator}).
+     *
+     * > Important: all properties following the `$body` should default to `null`, otherwise PHP will error because
+     * > it no longer matches the interface. This is why you often see the default tags check that an optional argument
+     * > is not null nonetheless.
+     *
+     * @param string             $body
+     * @param DescriptionFactory $descriptionFactory
+     * @param Context|null       $context The Context is used to resolve Types and FQSENs, although optional
+     *                                    it is highly recommended to pass it. If you omit it then it is assumed that
+     *                                    the DocBlock is in the global namespace and has no `use` statements.
+     *
+     * @see Tag for the interface declaration of the `create` method.
+     * @see Tag::create() for more information on this method's workings.
+     */
+    public static function create(string $body, DescriptionFactory $descriptionFactory = null, Context $context = null): self
+    {
+        Assert::notNull($descriptionFactory);
+
+        return new static($descriptionFactory->create($body, $context));
+    }
+
+    /**
+     * Returns a rendition of the original tag line.
+     *
+     * This method is used to reconstitute a DocBlock into its original form by the {@see Serializer}. It should
+     * feature all parts of the tag so that the serializer can put it back together.
+     */
+    public function __toString(): string
+    {
+        return (string)$this->description;
+    }
+}
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * @my-tag I have a description
+ */
+DOCCOMMENT;
+
+// Make a mapping between the tag name `my-tag` and the Tag class containing the Factory Method `create`.
+$customTags = ['my-tag' => MyTag::class];
+
+// Do pass the list of custom tags to the Factory for the DocBlockFactory.
+$factory = DocBlockFactory::createInstance($customTags);
+// You can also add Tags later using `$factory->registerTagHandler()` with a tag name and Tag class name.
+
+// Create the DocBlock
+$docblock = $factory->create($docComment);
+
+// Take a look: the $customTagObjects now contain an array with your newly added tag
+$customTagObjects = $docblock->getTagsByName('my-tag');
+
+// As an experiment: let's reconstitute the DocBlock and observe that because we added a __toString() method
+// to the tag class that we can now also see it.
+$serializer              = new Serializer(0, '',true, null, null, PHP_EOL);
+$reconstitutedDocComment = $serializer->getDocComment($docblock);

docs/examples/playing-with-descriptions/02-escaping.php

@@ -0,0 +1,47 @@
+<?php
+
+require_once(__DIR__ . '/../../../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlockFactory;
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * You can escape the @-sign by surrounding it with braces, for example: {@}. And escape a closing brace within an
+ * inline tag by adding an opening brace in front of it like this: {}.
+ *
+ * Here are example texts where you can see how they could be used in a real life situation:
+ *
+ *     This is a text with an {@internal inline tag where a closing brace ({}) is shown}.
+ *     Or an {@internal inline tag with a literal {{@}link{} in it}.
+ *
+ * Do note that an {@internal inline tag that has an opening brace ({) does not break out}.
+ */
+DOCCOMMENT;
+
+$factory  = DocBlockFactory::createInstance();
+$docblock = $factory->create($docComment);
+
+// Escaping is automatic so this happens in the DescriptionFactory.
+$description = $docblock->getDescription();
+
+// This is the rendition that we will receive of the Description.
+$receivedDocComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * You can escape the @-sign by surrounding it with braces, for example: {@}. And escape a closing brace within an
+ * inline tag by adding an opening brace in front of it like this: {}.
+ *
+ * Here are example texts where you can see how they could be used in a real life situation:
+ *
+ *     This is a text with an {@internal inline tag where a closing brace ({}) is shown}.
+ *     Or an {@internal inline tag with a literal {{@}link{} in it}.
+ *
+ * Do note that an {@internal inline tag that has an opening brace ({) does not break out}.
+ */
+DOCCOMMENT;
+
+// Render it using the default PassthroughFormatter
+$foundDescription = $description->render();

docs/how-to/adding-your-own-tag.rst

@@ -0,0 +1,9 @@
+How to Add Your Own Tag
+=======================
+
+This guide demonstrates how to add your own custom tag to a DocBlock using ReflectionDocBlock.
+
+.. literalinclude:: ../examples/04-adding-your-own-tag.php
+   :language: php
+   :linenos:
+

docs/how-to/index.rst

@@ -0,0 +1,13 @@
+How-to Guides
+=============
+
+Practical guides for common tasks with ReflectionDocBlock:
+
+.. toctree::
+   :maxdepth: 1
+
+   interpreting-a-simple-docblock
+   interpreting-tags
+   reconstituting-a-docblock
+   adding-your-own-tag
+

docs/how-to/interpreting-a-simple-docblock.rst

@@ -0,0 +1,9 @@
+How to Interpret a Simple DocBlock
+==================================
+
+This guide demonstrates how to parse a simple DocBlock and extract its summary and description using ReflectionDocBlock.
+
+.. literalinclude:: ../examples/01-interpreting-a-simple-docblock.php
+   :language: php
+   :linenos:
+

docs/how-to/interpreting-tags.rst

@@ -0,0 +1,9 @@
+How to Interpret Tags in a DocBlock
+===================================
+
+This guide demonstrates how to interpret tags within a DocBlock using ReflectionDocBlock.
+
+.. literalinclude:: ../examples/02-interpreting-tags.php
+   :language: php
+   :linenos:
+

docs/how-to/reconstituting-a-docblock.rst

@@ -0,0 +1,9 @@
+How to Reconstitute a DocBlock
+==============================
+
+ReflectionDocBlock not only allows you to read and interpret DocBlocks, but also to reconstruct them. This is useful if you need to add, remove, or modify tags in your codebase programmatically.
+
+.. literalinclude:: ../examples/03-reconstituting-a-docblock.php
+   :language: php
+   :linenos:
+

docs/index.rst

@@ -0,0 +1,42 @@
+ReflectionDocBlock Documentation
+===========================================
+
+ReflectionDocBlock is a PHP library that provides a DocBlock parser fully compatible with the PHPDoc standard. It allows you to parse, interpret, and extract information from DocBlocks in your PHP code, enabling support for annotations and metadata extraction.
+
+Key Features and Use Cases
+--------------------------
+- **Documentation Generation**: Used as a core component in tools like phpDocumentor to generate API documentation from your code's DocBlocks.
+- **Type and Metadata Extraction**: Integrations and tools use this library to gather type information and other metadata, enabling advanced features such as static analysis, code introspection, and automated serialization.
+- **Serializer Support**: Helps serializers and similar tools to interpret type information in array and object structures, making it easier to transform nested objects correctly.
+- **DocBlock Reconstitution**: Not only can you read DocBlocks, but you can also reconstruct them. This is useful for adding, removing, or modifying tags in your codebase programmatically.
+- **Standalone or Integrated**: Designed for standalone use, but also serves as a key component of the phpDocumentor suite.
+
+Unique Advantages
+-----------------
+- **Simple, Intuitive API**: Focus on ease of use, so you can work with DocBlocks without needing to understand the complexities of parsing.
+- **Widely Adopted**: Used by over 1000 packages on Packagist, making it a proven and reliable choice for PHP developers.
+- **Actively Maintained**: Supports PHP 7.4 and 8+, and is maintained by the phpDocumentor team and contributors.
+
+Quick Start Example
+-------------------
+Here's a minimal example of how to use ReflectionDocBlock in your project:
+
+.. code-block:: php
+   <?php
+   use phpDocumentor\Reflection\DocBlockFactory;
+
+   $factory  = DocBlockFactory::createInstance();
+   $docblock = $factory->create('/**\n * This is a summary.\n *\n * This is a description.\n */');
+
+   echo $docblock->getSummary(); // Outputs: This is a summary.
+
+For more detailed usage and how-to guides, see the ``examples/`` directory.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   how-to/index
+   migration-v6
+   contributing

docs/installation.rst

@@ -0,0 +1,9 @@
+Installation
+============
+
+To install ReflectionDocBlock, use Composer:
+
+.. code-block:: bash
+
+   composer require phpdocumentor/reflection-docblock
+

docs/upgrade-to-v6.rst

@@ -0,0 +1,7 @@
+
+Stop using ::create
+
+StandardTagFactory needs to be created via createInstance
+
+Method::getArguments removed
+Method::create is removed