Add comprehensive documentation for FastForward Defer

- Introduced `error-reporters.rst` detailing the Error Reporter API and built-in implementations.
- Added `event-dispatcher.rst` to explain PSR-14 event dispatcher integration and usage.
- Created `index.rst` for API reference overview, mapping public classes and interfaces.
- Developed `middleware.rst` to describe the DeferMiddleware for PSR-15 request handling.
- Added `support.rst` for CallbackDescriber utility documentation.
- Established `compatibility.rst` outlining runtime expectations and best practices.
- Expanded `examples/index.rst` with a structured learning path for practical usage.
- Created `faq.rst` addressing common questions about the library's functionality.
- Enhanced `getting-started.rst` with a minimal example and core concepts.
- Updated `index.rst` to provide a clearer introduction to the package.
- Revised `installation.rst` for clarity on installation steps and requirements.
- Added `dependencies.rst` summarizing package dependencies and integrations.
- Created `project-links.rst` for easy access to repository and documentation links.
- Updated PSR integration documentation for logger and middleware.
- Enhanced usage documentation with detailed examples and common pitfalls.
- Improved callback describer example to include static and instance methods.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

docs/advanced/callback-describer.rst

@@ -1,21 +1,75 @@
 Callback Describer
 ==================
 
-FastForward Defer includes a utility to describe any PHP callback in a human-readable way.
+``CallbackDescriber`` converts a PHP callable into a human-readable string.
+Built-in reporters use it so logs and events can tell you which deferred
+callback failed.
+
+Why it exists
+-------------
+
+Without a helper like this, generic error reporters would only know that "some
+callable" failed. ``CallbackDescriber`` adds context such as:
+
+- the function name
+- the class and method
+- the closure source file and line
+- whether the callback was an invokable object
+
+Supported callable shapes
+-------------------------
+
+- String function names such as ``'strlen'``
+- Array callables such as ``[SomeClass::class, 'handle']``
+- Closures
+- First-class callables, which are represented as closures
+- Invokable objects
 
 .. code-block:: php
 
    use FastForward\Defer\Support\CallbackDescriber;
 
-   $callback = function () {};
-   echo CallbackDescriber::describe($callback);
+   final class ExampleInvoker
+   {
+       public static function staticHandle(): void {}
 
-This is useful for debugging, logging, or event reporting.
+       public function handle(): void {}
 
-Supported callback types:
+       public function __invoke(): void {}
+   }
 
-- Named functions
-- Static methods
-- Object methods
-- Closures
-- Invokable objects
+   $object = new ExampleInvoker();
+
+   $callbacks = [
+       'strlen',
+       [ExampleInvoker::class, 'staticHandle'],
+       [$object, 'handle'],
+       static fn(): null => null,
+       ExampleInvoker::staticHandle(...),
+       $object,
+   ];
+
+   foreach ($callbacks as $callback) {
+       echo CallbackDescriber::describe($callback) . "\n";
+   }
+
+What to expect from the output
+------------------------------
+
+- String functions stay unchanged.
+- Array callables become ``Class::method`` or ``Class->method``.
+- Closures become ``Closure@/path/to/file.php:line``.
+- Invokable objects become ``Class::__invoke``.
+
+One subtle but important detail: first-class callables created with ``...`` are
+closures, so they are described as closures, not as ``Class::method``. If you
+want method-style output, pass an array callable instead.
+
+Where it is used
+----------------
+
+- ``ErrorLogErrorReporter``
+- ``PsrLoggerErrorReporter``
+- ``PsrEventDispatcherErrorReporter``
+
+See :doc:`../api/support` for the compact API reference.

docs/advanced/error-reporting.rst

@@ -1,53 +1,176 @@
 Error Reporting
-==============
+===============
 
-FastForward Defer provides robust error handling for deferred callbacks. Errors thrown by callbacks do not interrupt the execution chain; instead, they are reported via a pluggable error reporter.
+When a deferred callback throws, ``Defer`` catches that throwable and forwards
+it to the configured ``ErrorReporterInterface`` implementation. This keeps
+cleanup code from failing silently and lets you choose how much visibility you
+want in each environment.
 
-Default Behavior
+How reporting is configured
+---------------------------
+
+Error reporting is configured globally for ``Defer`` through the static
+``Defer::setErrorReporter()`` method.
+
+.. code-block:: php
+
+   use FastForward\Defer\Defer;
+   use FastForward\Defer\ErrorReporter\NullErrorReporter;
+
+   Defer::setErrorReporter(new NullErrorReporter());
+
+Every new ``Defer`` instance created after that call uses the configured
+reporter. Reset to the default ``error_log`` reporter with:
+
+.. code-block:: php
+
+   Defer::setErrorReporter(null);
+
+Built-in reporters at a glance
+------------------------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Class
+     - Purpose
+     - Good fit
+   * - ``ErrorLogErrorReporter``
+     - Writes a readable message to ``error_log()``
+     - Default behavior and simple production setups
+   * - ``NullErrorReporter``
+     - Ignores failures completely
+     - Tests or flows where cleanup noise must stay silent
+   * - ``CompositeErrorReporter``
+     - Sends the same failure to multiple reporters
+     - Logging plus metrics, logging plus events, and similar fan-out
+   * - ``PsrLoggerErrorReporter``
+     - Writes structured context to a PSR-3 logger
+     - Applications already using Monolog or another PSR-3 implementation
+   * - ``PsrEventDispatcherErrorReporter``
+     - Dispatches a ``DeferredCallbackFailed`` event
+     - Event-driven observability and decoupled listeners
+
+Default behavior
 ----------------
 
-By default, errors are reported using PHP's `error_log()`.
+If you never call ``Defer::setErrorReporter()``, the library lazily creates an
+``ErrorLogErrorReporter`` instance and logs messages like:
+
+- exception class and message
+- source file and line
+- a readable callback description
 
-Custom Error Reporter
----------------------
+Custom reporters
+----------------
 
-You MAY provide a custom error reporter by implementing `ErrorReporterInterface`:
+You can implement ``ErrorReporterInterface`` to forward failures anywhere you
+need.
 
 .. code-block:: php
 
    use FastForward\Defer\Defer;
    use FastForward\Defer\ErrorReporterInterface;
+   use Throwable;
 
    Defer::setErrorReporter(new class implements ErrorReporterInterface {
-       public function report(Throwable $throwable, ?callable $callback = null, array $args = []): void {
+       public function report(Throwable $throwable, ?callable $callback = null, array $arguments = []): void
+       {
            echo '[custom reporter] ' . $throwable::class . ': ' . $throwable->getMessage() . "\n";
        }
    });
 
+Important caveat
+----------------
+
+Custom reporters should not throw. ``Defer`` catches the deferred callback
+failure, but it does not wrap the reporter call in an extra safety layer. If
+your reporter throws, the remaining cleanup chain may stop early.
+
+If you need to defend against fragile reporters, wrap them with
+``CompositeErrorReporter`` or use reporters that already guard their own
+internal failures.
+
 NullErrorReporter
 -----------------
 
-Suppresses all error output:
+Use ``NullErrorReporter`` when you intentionally want silent cleanup failures.
 
 .. code-block:: php
 
    use FastForward\Defer\ErrorReporter\NullErrorReporter;
+
    Defer::setErrorReporter(new NullErrorReporter());
 
 CompositeErrorReporter
 ----------------------
 
-Allows reporting to multiple destinations:
+``CompositeErrorReporter`` fans a failure out to multiple reporters. It also
+catches failures thrown by one child reporter, logs that failure through
+``error_log()``, and keeps reporting to the remaining child reporters.
 
 .. code-block:: php
 
    use FastForward\Defer\ErrorReporter\CompositeErrorReporter;
    use FastForward\Defer\ErrorReporter\ErrorLogErrorReporter;
+   use FastForward\Defer\ErrorReporter\PsrEventDispatcherErrorReporter;
 
-   $stdoutReporter = new class implements ErrorReporterInterface {
-       public function report(Throwable $throwable, ?callable $callback = null, array $args = []): void {
-           echo '[stdout] ' . $throwable->getMessage() . "\n";
-       }
-   };
+   $reporter = new CompositeErrorReporter(
+       new ErrorLogErrorReporter(),
+       new PsrEventDispatcherErrorReporter($dispatcher),
+   );
+
+   if ($reporter->isEmpty()) {
+       $reporter->add(new ErrorLogErrorReporter());
+   }
+
+   Defer::setErrorReporter($reporter);
+
+The class also implements ``Countable``, which is useful in tests and diagnostic
+code.
+
+PSR-3 logger reporting
+----------------------
+
+``PsrLoggerErrorReporter`` sends a structured error entry to any
+``Psr\Log\LoggerInterface``.
+
+.. code-block:: php
+
+   use FastForward\Defer\ErrorReporter\PsrLoggerErrorReporter;
+
+   Defer::setErrorReporter(new PsrLoggerErrorReporter($logger));
+
+The context includes:
+
+- ``exception_class``
+- ``message``
+- ``file``
+- ``line``
+- ``callback``
+- ``callback_arguments``
+- ``exception``
+
+Because the reporter delegates directly to your logger, prefer a logger that
+does not throw during error handling.
+
+PSR-14 event reporting
+----------------------
+
+``PsrEventDispatcherErrorReporter`` dispatches a
+``FastForward\Defer\EventDispatcher\Event\DeferredCallbackFailed`` event.
+
+.. code-block:: php
+
+   use FastForward\Defer\ErrorReporter\PsrEventDispatcherErrorReporter;
+
+   Defer::setErrorReporter(new PsrEventDispatcherErrorReporter($dispatcher));
+
+This reporter is safer than a naïve custom reporter because it catches
+dispatcher failures internally and writes them to ``error_log()``.
+
+Related API
+-----------
 
-   Defer::setErrorReporter(new CompositeErrorReporter(new ErrorLogErrorReporter(), $stdoutReporter));
+See :doc:`../api/error-reporters` for class-by-class reference details and
+:doc:`../psr/index` for PSR-specific integration examples.

docs/advanced/index.rst

@@ -1,15 +1,17 @@
 Advanced Topics
 ===============
 
+These pages cover the parts of ``fast-forward/defer`` that matter once the
+basic mental model is already clear: controlling cleanup boundaries, integrating
+with applications, customizing error reporting, and understanding utility
+classes used by the built-in reporters.
+
 .. toctree::
    :maxdepth: 2
-   :caption: Advanced
+   :caption: Advanced:
 
    usage
    error-reporting
    integrations
    middleware
    callback-describer
-- Do not share instances across scopes
-- Prefer short-lived instances
-- Avoid long-lived/global usage