Add upgrade docs

Author: jaapio

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

docs/index.rst

@@ -21,22 +21,17 @@ 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
    :hidden:
 
    installation
    how-to/index
-   migration-v6
+   upgrade-to-v6
    contributing

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>`_