Update docs

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

Author: coisa

docs/examples/basic.rst

@@ -1,17 +1,60 @@
-Basic Example
-=============
+
+Basic Usage
+===========
+
+Registering and Fetching Services
+=================================
+
+This example shows how to register and retrieve services using the container helper.
 
 .. code-block:: php
 
+   use FastForward\Container\ServiceProvider\ArrayServiceProvider;
    use FastForward\Container\container;
+
+   $provider = new ArrayServiceProvider([
+       'logger' => fn() => new Monolog\Logger('app'),
+       'pdo' => fn() => new PDO('sqlite::memory:'),
+   ]);
+
+   $container = container($provider);
+   $logger = $container->get('logger');
+   $pdo = $container->get('pdo');
+
+Using Configuration to Register Providers
+========================================
+
+You can use a configuration object to register providers dynamically:
+
+.. code-block:: php
+
    use FastForward\Config\ArrayConfig;
+   use FastForward\Container\container;
+   use FastForward\Container\ServiceProvider\ArrayServiceProvider;
 
    $config = new ArrayConfig([
        FastForward\Container\ContainerInterface::class => [
-           SomeServiceProvider::class,
-           new OtherServiceProvider(),
+           new ArrayServiceProvider([
+               'cache' => fn() => new MyCache(),
+           ]),
        ],
    ]);
 
    $container = container($config);
-   $service = $container->get(SomeService::class);
+   $cache = $container->get('cache');
+
+Autowiring a Service (using PHP-DI)
+===================================
+
+The container supports autowiring for classes with type-hinted dependencies:
+
+.. code-block:: php
+
+   use FastForward\Container\container;
+
+   class MyService {
+       public function __construct(MyDependency $dep) { /* ... */ }
+   }
+
+   $container = container();
+   $service = $container->get(MyService::class); // MyDependency is autowired

docs/examples/factories.rst

@@ -1,18 +1,54 @@
-Factories Example
-=================
+
+Using Factories
+===============
+
+Using CallableFactory for Dependency Injection
+==============================================
 
 .. code-block:: php
 
    use FastForward\Container\Factory\CallableFactory;
+
+   $factory = new CallableFactory(fn($container) => new Mailer($container->get('logger')));
+   $mailer = $factory($container);
+
+Aliasing Services with AliasFactory
+==================================
+
+.. code-block:: php
+
    use FastForward\Container\Factory\AliasFactory;
+
+   $factory = new AliasFactory('mailer');
+   $sameMailer = $factory($container); // Returns the same as $container->get('mailer')
+
+Invoking Classes with InvokableFactory
+=====================================
+
+.. code-block:: php
+
    use FastForward\Container\Factory\InvokableFactory;
+
+   $factory = new InvokableFactory(MyService::class, 'arg1', 'arg2');
+   $service = $factory($container);
+
+Calling Static Methods with MethodFactory
+========================================
+
+.. code-block:: php
+
    use FastForward\Container\Factory\MethodFactory;
-   use FastForward\Container\Factory\ServiceFactory;
 
-   $callableFactory = new CallableFactory(fn($container) => new MyService($container->get(Dep::class)));
-   $aliasFactory = new AliasFactory('other_service');
-   $invokableFactory = new InvokableFactory(MyService::class, 'arg1');
-   $methodFactory = new MethodFactory(MyService::class, 'staticMethod', 'arg1');
-   $serviceFactory = new ServiceFactory(new MyService());
+   $factory = new MethodFactory(MyService::class, 'build', 'arg1');
+   $service = $factory($container);
+
+Wrapping Existing Instances with ServiceFactory
+==============================================
+
+.. code-block:: php
+
+   use FastForward\Container\Factory\ServiceFactory;
 
-   $service = $callableFactory($container);
+   $instance = new MyService();
+   $factory = new ServiceFactory($instance);
+   $service = $factory($container); // Always returns $instance

docs/examples/providers.rst

@@ -1,20 +1,68 @@
-Providers Example
-=================
+Registering Providers
+=====================
+
+Registering Multiple Providers
+=============================
 
 .. code-block:: php
 
    use FastForward\Container\ServiceProvider\ArrayServiceProvider;
    use FastForward\Container\ServiceProvider\AggregateServiceProvider;
-   use FastForward\Container\ServiceProviderContainer;
+   use FastForward\Container\container;
 
-   $provider1 = new ArrayServiceProvider([
-       'service' => fn() => new MyService(),
+   $providerA = new ArrayServiceProvider([
+       'mailer' => fn() => new Mailer(),
+   ]);
+   $providerB = new ArrayServiceProvider([
+       'notifier' => fn() => new Notifier(),
    ]);
-   $provider2 = new ArrayServiceProvider([
-       'other' => fn() => new OtherService(),
+
+   $container = container($providerA, $providerB);
+   $mailer = $container->get('mailer');
+   $notifier = $container->get('notifier');
+
+Extending Services with Providers
+=================================
+
+.. code-block:: php
+
+   use FastForward\Container\ServiceProvider\ArrayServiceProvider;
+   use FastForward\Container\container;
+
+   class UserRepository {
+       public function setLogger($logger) { /* ... */ }
+   }
+
+   $provider = new ArrayServiceProvider([
+       'user_repo' => fn() => new UserRepository(),
+       'logger' => fn() => new Logger('app'),
+   ], [
+       'user_repo' => function ($container, $repo) {
+           $repo->setLogger($container->get('logger'));
+           return $repo;
+       },
    ]);
 
-   $aggregate = new AggregateServiceProvider($provider1, $provider2);
-   $container = new ServiceProviderContainer($aggregate);
+   $container = container($provider);
+   $repo = $container->get('user_repo');
+
+Composing Providers for Feature Modules
+======================================
+
+.. code-block:: php
+
+   use FastForward\Container\ServiceProvider\ArrayServiceProvider;
+   use FastForward\Container\ServiceProvider\AggregateServiceProvider;
+   use FastForward\Container\container;
+
+   $userProvider = new ArrayServiceProvider([
+       'user_service' => fn() => new UserService(),
+   ]);
+   $authProvider = new ArrayServiceProvider([
+       'auth_service' => fn($container) => new AuthService($container->get('user_service')),
+   ]);
 
-   $service = $container->get('service');
+   $aggregate = new AggregateServiceProvider($userProvider, $authProvider);
+   $container = container($aggregate);
+   $userService = $container->get('user_service');
+   $authService = $container->get('auth_service');