Merge pull request #432 from phpDocumentor/docs

jaapio · web-flow · commit da3c60da1666 · 2026-01-05T21:53:28.000+01:00
Add docs
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,17 @@
+# https://docs.github.com/en/actions
+
+name: "Documentation"
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - "6.x"
+  workflow_dispatch: null
+
+jobs:
+  run:
+    name: "Documentation"
+    uses: "phpDocumentor/.github/.github/workflows/documentation.yml@main"
+    with:
+      deploy: true
+      component: "reflection-docblock"
diff --git a/.gitignore b/.gitignore
@@ -16,3 +16,5 @@ vendor/
 # By default the phpunit.xml.dist is provided; you can override this using a local config file
 phpunit.xml
 .phpunit.result.cache
+
+.phpdoc
diff --git a/Makefile b/Makefile
@@ -41,3 +41,7 @@ rector: ## Refactor code using rector
 
 .PHONY: pre-commit-test
 pre-commit-test: fix-code-style test code-style static-code-analysis
+
+.PHONY: docs
+docs: ## Generate documentation with phpDocumentor
+	docker run -it --rm -v${PWD}:/opt/project -w /opt/project phpdoc/phpdoc:3
diff --git a/docs/contributing.rst b/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.
+
diff --git a/docs/examples/01-interpreting-a-simple-docblock.php b/docs/examples/01-interpreting-a-simple-docblock.php
@@ -1,5 +1,5 @@
 <?php
-require_once(__DIR__ . '/../vendor/autoload.php');
+require_once(__DIR__ . '/../../vendor/autoload.php');
 
 use phpDocumentor\Reflection\DocBlockFactory;
 
diff --git a/docs/examples/02-interpreting-tags.php b/docs/examples/02-interpreting-tags.php
@@ -1,5 +1,5 @@
 <?php
-require_once(__DIR__ . '/../vendor/autoload.php');
+require_once(__DIR__ . '/../../vendor/autoload.php');
 
 use phpDocumentor\Reflection\DocBlockFactory;
 
diff --git a/docs/examples/03-reconstituting-a-docblock.php b/docs/examples/03-reconstituting-a-docblock.php
@@ -1,6 +1,6 @@
 <?php
 
-require_once(__DIR__ . '/../vendor/autoload.php');
+require_once(__DIR__ . '/../../vendor/autoload.php');
 
 use phpDocumentor\Reflection\DocBlock\Serializer;
 use phpDocumentor\Reflection\DocBlockFactory;
diff --git a/docs/examples/04-adding-your-own-tag.php b/docs/examples/04-adding-your-own-tag.php
@@ -3,7 +3,7 @@
  * 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');
+require_once(__DIR__ . '/../../vendor/autoload.php');
 
 use phpDocumentor\Reflection\DocBlock\Serializer;
 use phpDocumentor\Reflection\DocBlock\Tag;
diff --git a/docs/examples/playing-with-descriptions/02-escaping.php b/docs/examples/playing-with-descriptions/02-escaping.php
@@ -1,6 +1,6 @@
 <?php
 
-require_once(__DIR__ . '/../../vendor/autoload.php');
+require_once(__DIR__ . '/../../../vendor/autoload.php');
 
 use phpDocumentor\Reflection\DocBlockFactory;
 
diff --git a/docs/how-to/adding-your-own-tag.rst b/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:
+
diff --git a/docs/how-to/index.rst b/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
+
diff --git a/docs/how-to/interpreting-a-simple-docblock.rst b/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:
+
diff --git a/docs/how-to/interpreting-tags.rst b/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:
+
diff --git a/docs/how-to/reconstituting-a-docblock.rst b/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:
+
diff --git a/docs/index.rst b/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
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -0,0 +1,9 @@
+Installation
+============
+
+To install ReflectionDocBlock, use Composer:
+
+.. code-block:: bash
+
+   composer require phpdocumentor/reflection-docblock
+
diff --git a/docs/upgrade-to-v6.rst b/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
diff --git a/phpdoc.dist.xml b/phpdoc.dist.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdocumentor
+        configVersion="3"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://www.phpdoc.org"
+        xsi:noNamespaceSchemaLocation="data/xsd/phpdoc.xsd"
+>
+    <title>Reflection Docblock</title>
+    <paths>
+        <output>build/docs</output>
+    </paths>
+    <version number="6.0.0">
+        <folder>latest</folder>
+        <api>
+            <source dsn="./">
+                <path>src/</path>
+            </source>
+            <output>api</output>
+            <ignore hidden="true" symlinks="true">
+                <path>tests/**/*</path>
+                <path>build/**/*</path>
+                <path>var/**/*</path>
+                <path>vendor/**/*</path>
+            </ignore>
+            <extensions>
+                <extension>php</extension>
+            </extensions>
+            <ignore-tags>
+                <ignore-tag>template</ignore-tag>
+                <ignore-tag>template-extends</ignore-tag>
+                <ignore-tag>template-implements</ignore-tag>
+                <ignore-tag>extends</ignore-tag>
+                <ignore-tag>implements</ignore-tag>
+            </ignore-tags>
+            <default-package-name>phpDocumentor</default-package-name>
+        </api>
+        <guide>
+            <source dsn=".">
+                <path>docs</path>
+            </source>
+            <output>guides</output>
+        </guide>
+    </version>
+    <setting name="guides.enabled" value="true"/>
+    <template name="default" />
+</phpdocumentor>
diff --git a/tests/integration/InterpretingDocBlocksTest.php b/tests/integration/InterpretingDocBlocksTest.php
@@ -86,7 +86,7 @@ public function testInterpretingASimpleDocBlock(): void
         /** @var Description $description */
         $description;
 
-        include(__DIR__ . '/../../examples/01-interpreting-a-simple-docblock.php');
+        include(__DIR__ . '/../../docs/examples/01-interpreting-a-simple-docblock.php');
 
         $descriptionText = <<<DESCRIPTION
 This is a Description. A Summary and Description are separated by either
@@ -120,7 +120,7 @@ public function testInterpretingTags(): void
         /** @var See[] $seeTags */
         $seeTags;
 
-        include(__DIR__ . '/../../examples/02-interpreting-tags.php');
+        include(__DIR__ . '/../../docs/examples/02-interpreting-tags.php');
 
         $this->assertTrue($hasSeeTag);
         $this->assertCount(1, $tags);
@@ -147,7 +147,7 @@ public function testDescriptionsCanEscapeAtSignsAndClosingBraces(): void
         /** @var string $foundDescription */
         $foundDescription;
 
-        include(__DIR__ . '/../../examples/playing-with-descriptions/02-escaping.php');
+        include(__DIR__ . '/../../docs/examples/playing-with-descriptions/02-escaping.php');
 
         $this->assertSame(
             str_replace(
diff --git a/tests/integration/ReconstitutingADocBlockTest.php b/tests/integration/ReconstitutingADocBlockTest.php
@@ -39,7 +39,7 @@ public function testReconstituteADocBlock(): void
         /** @var string $reconstitutedDocComment */
         $reconstitutedDocComment;
 
-        include(__DIR__ . '/../../examples/03-reconstituting-a-docblock.php');
+        include(__DIR__ . '/../../docs/examples/03-reconstituting-a-docblock.php');
 
         $this->assertSame($docComment, $reconstitutedDocComment);
     }
diff --git a/tests/integration/UsingTagsTest.php b/tests/integration/UsingTagsTest.php
@@ -40,7 +40,7 @@ public function testAddingYourOwnTagUsingAStaticMethodAsFactory(): void
         /** @var string $reconstitutedDocComment */
         $reconstitutedDocComment;
 
-        include(__DIR__ . '/../../examples/04-adding-your-own-tag.php');
+        include(__DIR__ . '/../../docs/examples/04-adding-your-own-tag.php');
 
         $this->assertInstanceOf(\MyTag::class, $customTagObjects[0]);
         $this->assertSame('my-tag', $customTagObjects[0]->getName());
