From 02600c041e7d0f4b7d1fe1d260565ec525472fa9 Mon Sep 17 00:00:00 2001
From: Jaapio <jaap@ijaap.nl>
Date: Wed, 7 Jan 2026 21:16:44 +0100
Subject: [PATCH] Add upgrade docs

---
 docs/how-to/reconstituting-a-docblock.rst | 11 ++---
 docs/index.rst                            | 15 +++----
 docs/upgrade-to-v6.rst                    | 52 +++++++++++++++++++++--
 3 files changed, 59 insertions(+), 19 deletions(-)

diff --git a/docs/how-to/reconstituting-a-docblock.rst b/docs/how-to/reconstituting-a-docblock.rst
index 84ed201..2bc0e88 100644
--- a/docs/how-to/reconstituting-a-docblock.rst
+++ b/docs/how-to/reconstituting-a-docblock.rst
@@ -1,9 +1,10 @@
-Reconstitute a DocBlock
-==============================
+Reconstituting 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.
+ReflectionDocBlock not only allows you to read and parse DocBlocks, but also to reconstruct them. This is useful if you need to add, remove, or modify tags in your codebase programmatically. For example, you might want to update type information, add custom tags, or strip deprecated tags as part of a refactoring or code generation process.
+
+Below is a practical example of how to reconstitute a DocBlock using this library:
 
 .. literalinclude:: ../examples/03-reconstituting-a-docblock.php
    :language: php
-   :linenos:
-
+   :caption: examples/03-reconstituting-a-docblock.php
diff --git a/docs/index.rst b/docs/index.rst
index e59d9d2..05345c1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -21,16 +21,11 @@ Quick Start Example
 -------------------
 Here's a minimal example of how to use ReflectionDocBlock in your project:
 
-.. code-block:: php
-   <?php
-   use phpDocumentor\Reflection\DocBlockFactory;
+.. literalinclude:: examples/01-interpreting-a-simple-docblock.php
+   :language: php
+   :caption: examples/01-interpreting-a-simple-docblock.php
 
-   $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.
+For more detailed usage and how-to guides, see the ``how-to/`` section.
 
 .. toctree::
    :maxdepth: 2
@@ -38,5 +33,5 @@ For more detailed usage and how-to guides, see the ``examples/`` directory.
 
    installation
    how-to/index
-   migration-v6
+   upgrade-to-v6
    contributing
diff --git a/docs/upgrade-to-v6.rst b/docs/upgrade-to-v6.rst
index 7a55dce..1ccc8e7 100644
--- a/docs/upgrade-to-v6.rst
+++ b/docs/upgrade-to-v6.rst
@@ -1,7 +1,51 @@
+Upgrade Guide to v6
+===================
 
-Stop using ::create
+This guide helps you upgrade your project to ReflectionDocBlock v6. It covers breaking changes, removals, new features, and migration tips to ensure a smooth transition.
 
-StandardTagFactory needs to be created via createInstance
+Supported PHP Versions
+----------------------
+- v6 requires PHP 7.4 or higher (PHP 8+ recommended).
 
-Method::getArguments removed
-Method::create is removed
+Breaking Changes & Removals
+---------------------------
+- **Removal of `::create` static method for type-based tags**
+  - The `create` static method has been removed from tag classes that represent type definitions, such as `@param` and `@return` tags. Most users will not be affected, as these methods are rarely used directly. The deprecation notice for these methods was present throughout v5.
+  - **Migration:**
+    - If you are instantiating these tag objects directly, use the tag factory or the recommended construction pattern instead.
+    - Before:
+      .. code-block:: php
+
+         $tag = Param::create($body);
+    - After:
+      .. code-block:: php
+
+         $factory = \phpDocumentor\Reflection\DocBlock\Tags\Factory\StandardTagFactory::createInstance();
+         $tag = $factory->create('@param int $foo');
+
+- **StandardTagFactory instantiation**
+  - `StandardTagFactory` must now be created via `createInstance()`.
+  - **Migration:**
+    - Before:
+      .. code-block:: php
+
+         $factory = new StandardTagFactory();
+    - After:
+      .. code-block:: php
+
+         $factory = StandardTagFactory::createInstance();
+
+- **Removed methods**
+  - `Method::getArguments` has been removed.
+  - `Method::create` has been removed.
+  - **Migration:**
+    - Refactor code to use the new API for method arguments and creation.
+
+TypeResolver Upgrade
+-------------------
+- **Generics Support**: The TypeResolver component now supports generics,
+    which replaces the previous `Collection` type handling. This allows
+    for more accurate and expressive type definitions, such as `MyClass<int, MyClass>` or `Collection<MyClass>`,
+    and improves compatibility with modern PHPDoc standards.
+
+- For more details and advanced migration scenarios, consult the `TypeResolver upgrade guide <https://docs.phpdoc.org/components/type-resolver/guides/upgrade-v1-to-v2.html#upgrade-to-version-2>`_