updated modules.docs

Author: eadwinCode

docs/overview/controllers.md

@@ -327,10 +327,7 @@ from .controllers import CarController
     routers=[],
 )
 class CarModule(ModuleBase):
-    def register_providers(self, container: Container) -> None:
-        # for more complicated provider registrations
-        # container.register_instance(...)
-        pass
+    pass
 ```
 
 ![controller_dog.gif](../img/car_controller.gif)

docs/overview/guards.md

@@ -143,10 +143,7 @@ from .guards import RoleGuard
     providers=[CarRepository, ProviderConfig(GlobalGuard, use_class=RoleGuard)]
 )
 class CarModule(ModuleBase):
-    def register_providers(self, container: Container) -> None:
-        # for more complicated provider registrations
-        # container.register_instance(...)
-        pass
+    pass
 
 ```
 

docs/overview/module-router.md

@@ -67,10 +67,7 @@ from .routers import math_router
     routers=[math_router],
 )
 class CarModule(ModuleBase):
-    def register_providers(self, container: Container) -> None:
-        # for more complicated provider registrations
-        # container.register_instance(...)
-        pass
+    pass
 ```
 
 ![math_router.png](../img/math_router.png)

docs/overview/modules.md

@@ -31,9 +31,7 @@ from .controllers import CarController
     providers=[CarRepository],
 )
 class CarModule(ModuleBase):
-    def register_providers(self, container: Container) -> None:
-        # Additional provider registrations can be done here
-        pass
+    pass
 ```
 
 ## **Module Parameters**
@@ -179,15 +177,10 @@ from .controllers import CarController
 class CarModule(ModuleBase):
     def __init__(self, config: Config):
         self.config = config
-    
-    def register_providers(self, container: Container) -> None:
-        # Additional provider registrations can be performed here
-        pass
 ```
 
 In this example, the `CarModule` class accepts a `Config` object in its constructor. 
 This allows us to access configuration parameters within the module. 
-Additionally, the `register_providers` method can be utilized for more advanced provider registrations within the container.
 
 ## **Module Middleware**
 Middleware functions can be defined at the module level using the `@middleware()` function decorator. Let's illustrate this with an example:
@@ -264,9 +257,42 @@ you can refer to the documentation [here](https://injector.readthedocs.io/en/lat
 ## **ForwardRefModule**
 `ForwardRefModule` is a powerful feature that allows you to reference a `@Module()` class in your application 
 without needing to instantiate or configure it directly at the point of reference. 
+
 This is particularly useful in scenarios where you have circular dependencies between modules 
 or when you want to declare dependencies without tightly coupling your modules.
 
+#### What problem does it solve?    
+Let's consider an example where we have two modules, `ModuleA` and `ModuleB`. `ModuleB` depends on a service/provider, which is exported, from `ModuleA` and `ModuleB` does not want to instantiate `ModuleA` directly but rather reference its existing instance from the application scope. `ModuleB` can use `ForwardRefModule` to declare the `ModuleA` as a dependency. And `ModuleA` can be setup differently in any random order.
+
+A typical example is a `CustomModule` that depends on `JWTModule` to sign the JWT tokens. The `CustomModule` would declare `JWTModule` as a dependency using `ForwardRefModule` and `JWTModule` can be configured separately in `ApplicationModule`.
+
+```python
+from ellar.common import Module
+from ellar.core import ModuleBase, ForwardRefModule
+from ellar_jwt import JWTModule, JWTService
+
+
+@Module(name="CustomModule", modules=[ForwardRefModule(JWTModule)])
+class CustomModule(ModuleBase):
+    def __init__(self, jwt_service: JWTService):
+        self.jwt_service = jwt_service
+        assert self.jwt_service
+
+
+@Module(modules=[
+    CustomModule, 
+    JWTModule.setup(secret_key="super-secret")
+])
+class ApplicationModule(ModuleBase):
+    pass
+```
+The `JWTModule` provides `JWTService` which is injected into `CustomModule`. By declaring `ForwardRefModule(JWTModule)` in `CustomModule`, the `JWTService` will be properly resolved during instantiation of `CustomModule`, regardless of the order in which the modules are configured in the application.
+
+This pattern is particularly useful when:
+- You want to avoid direct module instantiation
+- You need to configure a module differently in different parts of your application
+- You want to maintain loose coupling between modules
+
 ### Forward Reference by Class
 
 In the following example, we have two modules, `ModuleA` and `ModuleB`. `ModuleB` 

docs/overview/providers.md

@@ -111,10 +111,7 @@ from .controllers import CarController
     routers=[],
 )
 class CarModule(ModuleBase):
-    def register_providers(self, container: Container) -> None:
-        # for more complicated provider registrations
-        # container.register_instance(...)
-        pass
+    pass
 ```
 
 By adding `CarRepository` to the list of providers, Ellar ensures that it is available for dependency injection within the `CarModule`. 
@@ -159,7 +156,8 @@ a_foo_instance = AFooClass()
 @Module(
     providers=[
         ProviderConfig(IFoo, use_class=AFooClass),
-        ProviderConfig(IFooB, use_value=a_foo_instance)
+        ProviderConfig(IFooB, use_value=a_foo_instance),
+        ProviderConfig(IFoo, use_class="path.to:AFooClass")
     ]
 )
 class AModule(ModuleBase):
@@ -184,66 +182,7 @@ if __name__ == "__main__":
     validate_provider_config()
 ```
 
-In the above example, `ProviderConfig` is used as a value type for `IFooB` and as a concrete type for `IFoo`.
-
-### **2. `register_providers`:**
-Another method is by overriding `register_services` in any Module class.
-
-For example:
-```python
-# main.py
-
-from ellar.common import Module
-from ellar.core import ModuleBase, Config
-from ellar.di import Container, EllarInjector, injectable
-from ellar.core.modules.ref import create_module_ref_factor
-
-injector = EllarInjector(auto_bind=False)
-
-
-class IFoo:
-    pass
-
-
-class IFooB:
-    pass
-
-
-@injectable
-class AFooClass(IFoo, IFooB):
-    pass
-
-
-a_foo_instance = AFooClass()
-
-
-@Module()
-class AModule(ModuleBase):
-    def register_services(self, container: Container) -> None:
-        container.register(IFoo, AFooClass)
-        container.register(IFooB, a_foo_instance)
-
-
-def validate_register_services():
-    module_ref = create_module_ref_factor(
-       AModule, container=injector.container, config=Config(),
-    )
-    module_ref.run_module_register_services()
-    
-    ifoo_b = injector.get(IFooB)
-    ifoo = injector.get(IFoo)
-    
-    assert isinstance(ifoo_b, AFooClass)
-    assert isinstance(ifoo, AFooClass)
-    assert ifoo_b == a_foo_instance
-
-if __name__ == "__main__":
-    validate_register_services()
-
-```
-
-In the illustration above, the `AModule` `register_services` method was used to register `IFoo` and `IFooB`
-with their respective concrete implementations.
+In the above example, `ProviderConfig` is used as a value type for `IFooB` and as a concrete type for `IFoo`. Also, the `use_class` argument can be used to specify the path to the class to be used as the provider which is useful when you want to lazy load the provider class.
 
 ## **Tagging Registered Providers**
 
@@ -264,40 +203,23 @@ class Foo:
 class FooB:
     pass
 
-injector.container.register_singleton(Foo, tag="first_foo")
-injector.container.register(FooB, tag="second_foo")
 
-first_foo_instance = injector.get("first_foo")
-second_foo_instance = injector.get("second_foo")
+@Module(
+    providers=[
+        ProviderConfig(Foo, tag="first_foo"),
+        ProviderConfig(FooB, tag="second_foo"),
+    ]
+)
+class AModule(ModuleBase):
+    def __init__(self, foo: InjectByTag("first_foo"), foo_b: InjectByTag("second_foo")):
+        self.foo = foo
+        self.foo_b = foo_b
 
-assert first_foo_instance is injector.get(Foo)
-assert isinstance(second_foo_instance, Foo)
+        assert isinstance(self.foo, Foo)
+        assert isinstance(self.foo_b, FooB)
 ```
 
 In the above example, we are tagging `Foo` as `first_foo` and `FooB` as `second_foo`. By doing this, we can resolve both services using their tag names, thus providing the possibility of resolving services by tag name or type.
 
-Also, services can be injected as a dependency by using tags. To achieve this, the `InjectByTag` decorator is used.
-
-For example:
-
-```python
-from ellar.di import EllarInjector, InjectByTag, scopes
-
-injector = EllarInjector(auto_bind=False)
-
-
-class Foo:
-    name: str = "foo"
-
-
-class FooB:
-    def __init__(self, foo: InjectByTag("fooTag")):
-        self.foo = foo
-
-injector.container.register(Foo, tag="fooTag", scope=scopes.singleton_scope)
-injector.container.register(FooB)
-
-assert injector.get(FooB).foo == 'foo'
-```
-
+Also, services can be injected as a dependency by using tags. To achieve this, the `InjectByTag` decorator is used as a `**constructor**` argument.
 This allows for more flexibility in managing dependencies and resolving services based on tags.

docs/quick-project.md

@@ -220,10 +220,7 @@ from .services import CarDummyDB
     routers=[],
 )
 class CarModule(ModuleBase):
-    def register_providers(self, container: Container) -> None:
-        # for more complicated provider registrations
-        # container.register_instance(...)
-        pass
+    pass
 ```
 
 ## **Registering Module**

docs/techniques/staticfiles.md

@@ -51,10 +51,7 @@ from .controllers import CarController
     controllers=[CarController], static_folder='my_static'
 )
 class CarModule(ModuleBase):
-    def register_providers(self, container: Container) -> None:
-        # for more complicated provider registrations
-        # container.register_instance(...)
-        pass
+    pass
 ```
 
 ## **Other Static Configurations**

ellar/core/modules/base.py

@@ -115,7 +115,7 @@ def post_build(cls, module_ref: "ModuleRefBase") -> None:
         """Executed after a Subclass build process is done"""
 
     def register_services(self, container: Container) -> None:
-        """Register other services manually"""
+        """This method is used to register other services manually. But its advised to use the `ProviderConfig` class instead."""
 
     def configure(self, container: Binder) -> None:
         """Injector Module Support. Override register_services instead"""