From cd04bb47b5693f7653a1175468a635e69a6b0859 Mon Sep 17 00:00:00 2001
From: Jaapio <jaap@ijaap.nl>
Date: Mon, 5 Jan 2026 20:49:06 +0100
Subject: [PATCH 1/2] Add docs

---
 .gitignore                                    |  2 +
 Makefile                                      |  4 ++
 docs/contributing.rst                         | 12 +++++
 .../01-interpreting-a-simple-docblock.php     |  2 +-
 .../examples}/02-interpreting-tags.php        |  2 +-
 .../03-reconstituting-a-docblock.php          |  2 +-
 .../examples}/04-adding-your-own-tag.php      |  2 +-
 .../playing-with-descriptions/02-escaping.php |  2 +-
 docs/how-to/adding-your-own-tag.rst           |  9 ++++
 docs/how-to/index.rst                         | 13 ++++++
 .../how-to/interpreting-a-simple-docblock.rst |  9 ++++
 docs/how-to/interpreting-tags.rst             |  9 ++++
 docs/how-to/reconstituting-a-docblock.rst     |  9 ++++
 docs/index.rst                                | 42 +++++++++++++++++
 docs/installation.rst                         |  9 ++++
 docs/upgrade-to-v6.rst                        |  7 +++
 phpdoc.dist.xml                               | 46 +++++++++++++++++++
 .../integration/InterpretingDocBlocksTest.php |  6 +--
 .../ReconstitutingADocBlockTest.php           |  2 +-
 tests/integration/UsingTagsTest.php           |  2 +-
 20 files changed, 181 insertions(+), 10 deletions(-)
 create mode 100644 docs/contributing.rst
 rename {examples => docs/examples}/01-interpreting-a-simple-docblock.php (93%)
 rename {examples => docs/examples}/02-interpreting-tags.php (91%)
 rename {examples => docs/examples}/03-reconstituting-a-docblock.php (93%)
 rename {examples => docs/examples}/04-adding-your-own-tag.php (99%)
 rename {examples => docs/examples}/playing-with-descriptions/02-escaping.php (96%)
 create mode 100644 docs/how-to/adding-your-own-tag.rst
 create mode 100644 docs/how-to/index.rst
 create mode 100644 docs/how-to/interpreting-a-simple-docblock.rst
 create mode 100644 docs/how-to/interpreting-tags.rst
 create mode 100644 docs/how-to/reconstituting-a-docblock.rst
 create mode 100644 docs/index.rst
 create mode 100644 docs/installation.rst
 create mode 100644 phpdoc.dist.xml

diff --git a/.gitignore b/.gitignore
index 62394e1a..581a7f0c 100644
--- 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
index 5420da71..05849d2a 100644
--- 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
new file mode 100644
index 00000000..a016ce46
--- /dev/null
+++ 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/examples/01-interpreting-a-simple-docblock.php b/docs/examples/01-interpreting-a-simple-docblock.php
similarity index 93%
rename from examples/01-interpreting-a-simple-docblock.php
rename to docs/examples/01-interpreting-a-simple-docblock.php
index 6d67dea4..d95d455f 100644
--- a/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/examples/02-interpreting-tags.php b/docs/examples/02-interpreting-tags.php
similarity index 91%
rename from examples/02-interpreting-tags.php
rename to docs/examples/02-interpreting-tags.php
index 23995889..ba0ca400 100644
--- a/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/examples/03-reconstituting-a-docblock.php b/docs/examples/03-reconstituting-a-docblock.php
similarity index 93%
rename from examples/03-reconstituting-a-docblock.php
rename to docs/examples/03-reconstituting-a-docblock.php
index 482a6dd1..d0b042dd 100644
--- a/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/examples/04-adding-your-own-tag.php b/docs/examples/04-adding-your-own-tag.php
similarity index 99%
rename from examples/04-adding-your-own-tag.php
rename to docs/examples/04-adding-your-own-tag.php
index 38ab7248..2e7ff75e 100644
--- a/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/examples/playing-with-descriptions/02-escaping.php b/docs/examples/playing-with-descriptions/02-escaping.php
similarity index 96%
rename from examples/playing-with-descriptions/02-escaping.php
rename to docs/examples/playing-with-descriptions/02-escaping.php
index 5ec772fe..a215303a 100644
--- a/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
new file mode 100644
index 00000000..64464d82
--- /dev/null
+++ 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
new file mode 100644
index 00000000..3f90b0a5
--- /dev/null
+++ 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
new file mode 100644
index 00000000..b537c909
--- /dev/null
+++ 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
new file mode 100644
index 00000000..fdea6f6e
--- /dev/null
+++ 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
new file mode 100644
index 00000000..cade5787
--- /dev/null
+++ 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
new file mode 100644
index 00000000..6ac3482d
--- /dev/null
+++ 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
new file mode 100644
index 00000000..13232061
--- /dev/null
+++ 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
index e69de29b..7a55dce2 100644
--- 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
new file mode 100644
index 00000000..3b02e31b
--- /dev/null
+++ 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
index 698aac96..4ea86680 100644
--- 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
index aef6598c..07b30411 100644
--- 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
index eb463d8d..e7c8bbc0 100644
--- 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());

From febafae9b0a612a5b4e18ea9ca093aa93c98648a Mon Sep 17 00:00:00 2001
From: Jaapio <jaap@ijaap.nl>
Date: Mon, 5 Jan 2026 21:52:34 +0100
Subject: [PATCH 2/2] Add auto deploy

---
 .github/workflows/documentation.yml | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 .github/workflows/documentation.yml

diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
new file mode 100644
index 00000000..369a011a
--- /dev/null
+++ 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"