Merge pull request #309 from python-ellar/code_documentation

chores: Adding more code documentation Part 1

Author: eadwinCode

ellar/app/context.py

@@ -16,9 +16,12 @@
 @ensure_build_context(app_ready=True)
 def ensure_available_in_providers(*items: t.Any) -> None:
     """
-    Ensures that Providers at least belows to a particular module
-    :param items:
-    :return:
+    Ensures that Providers belong to a particular module.
+
+    If a provider is not found in any existing module, it is added to the
+    application module and exported.
+
+    :param items: List of providers to check.
     """
     app_module = current_injector.tree_manager.get_app_module()
 
@@ -43,9 +46,9 @@ def _(data: TreeData) -> bool:
 @ensure_build_context(app_ready=True)
 def use_authentication_schemes(*authentication: AuthenticationHandlerType) -> None:
     """
-    Registered Authentication Handlers to the application
-    :param authentication:
-    :return:
+    Registers Authentication Handlers to the application.
+
+    :param authentication: List of authentication handlers or schemes.
     """
     __identity_scheme = current_injector.get(IIdentitySchemes)
     for auth in authentication:
@@ -58,9 +61,9 @@ def use_exception_handler(
     *exception_handlers: IExceptionHandler,
 ) -> None:
     """
-    Adds Application Exception Handlers
-    :param exception_handlers: IExceptionHandler
-    :return:
+    Adds Application Exception Handlers.
+
+    :param exception_handlers: List of exception handlers to register.
     """
     for exception_handler in exception_handlers:
         if exception_handler not in current_config.EXCEPTION_HANDLERS:
@@ -78,12 +81,12 @@ def enable_versioning(
     **init_kwargs: t.Any,
 ) -> None:
     """
-    Enables an Application Versioning scheme
-    :param schema: VersioningSchemes
-    :param version_parameter: versioning parameter lookup key. Default: 'version'
-    :param default_version: versioning default value. Default: None
-    :param init_kwargs: Other schema initialization keyword args.
-    :return:
+    Enables an Application Versioning scheme.
+
+    :param schema: The versioning scheme to use (e.g., URL, Header, Query).
+    :param version_parameter: The parameter name for version lookup. Default: 'version'.
+    :param default_version: The default version to use if none is specified. Default: None.
+    :param init_kwargs: Additional initialization arguments for the versioning scheme.
     """
     current_config.VERSIONING_SCHEME = schema.value(
         version_parameter=version_parameter,
@@ -97,9 +100,9 @@ def use_global_guards(
     *guards: t.Union[GuardCanActivate, t.Type[GuardCanActivate]],
 ) -> None:
     """
-    Registers Application Global Guards that affects all routes registered in ApplicationRouter
-    :param guards:
-    :return: None
+    Registers Application Global Guards that affect all routes registered in the ApplicationRouter.
+
+    :param guards: List of guards to register globally.
     """
     current_config.GLOBAL_GUARDS = list(current_config.GLOBAL_GUARDS) + list(guards)
     ensure_available_in_providers(*guards)
@@ -110,9 +113,9 @@ def use_global_interceptors(
     *interceptors: t.Union[EllarInterceptor, t.Type[EllarInterceptor]],
 ) -> None:
     """
-    Registers Application Global Interceptor that affects all routes registered in ApplicationRouter
-    :param interceptors:
-    :return: None
+    Registers Application Global Interceptors that affect all routes registered in the ApplicationRouter.
+
+    :param interceptors: List of interceptors to register globally.
     """
     current_config.GLOBAL_INTERCEPTORS = list(
         current_config.GLOBAL_INTERCEPTORS

ellar/app/factory.py

@@ -34,7 +34,9 @@
 
 class AppFactory:
     """
-    Factory for creating Ellar Application
+    Factory for creating Ellar Application instances.
+
+    Provides methods to create an application from a module, controller, or existing app module.
     """
 
     @classmethod
@@ -189,6 +191,22 @@ def create_app(
         config_module: t.Union[str, t.Dict, None] = None,
         injector: t.Optional[EllarInjector] = None,
     ) -> App:
+        """
+        Creates an Ellar Application instance.
+
+        :param controllers: List of controllers to register.
+        :param routers: List of routers to register.
+        :param providers: List of providers to register.
+        :param modules: List of modules to register.
+        :param template_folder: Path to the template folder.
+        :param base_directory: Path to the base directory.
+        :param static_folder: Name of the static folder. Default: "static".
+        :param global_guards: List of global guards to register.
+        :param commands: List of commands to register.
+        :param config_module: Configuration module or dictionary.
+        :param injector: Optional existing injector instance.
+        :return: Configured App instance.
+        """
         module = Module(
             controllers=controllers,
             routers=routers,
@@ -219,6 +237,15 @@ def create_from_app_module(
         injector: t.Optional[EllarInjector] = None,
         config_module: t.Union[str, t.Dict, None] = None,
     ) -> App:
+        """
+        Creates an Ellar Application from an existing Application Module.
+
+        :param module: The application module class.
+        :param global_guards: List of global guards to register.
+        :param injector: Optional existing injector instance.
+        :param config_module: Configuration module or dictionary.
+        :return: Configured App instance.
+        """
         app = cls._create_app(
             module,
             config_module=config_module,

ellar/app/main.py

@@ -44,6 +44,10 @@
 
 
 class App:
+    """
+    The main Ellar Application class.
+    """
+
     def __init__(
         self,
         config: "Config",
@@ -117,6 +121,11 @@ def get_interceptors(
     async def use_global_guards(
         self, *guards: t.Union["GuardCanActivate", t.Type["GuardCanActivate"]]
     ) -> None:
+        """
+        Registers global guards for the application.
+
+        :param guards: Guards to register.
+        """
         async with self.with_injector_context():
             use_global_guards(*guards)
 
@@ -125,6 +134,11 @@ async def use_global_guards(
     async def use_global_interceptors(
         self, *interceptors: t.Union[EllarInterceptor, t.Type[EllarInterceptor]]
     ) -> None:
+        """
+        Registers global interceptors for the application.
+
+        :param interceptors: Interceptors to register.
+        """
         async with self.with_injector_context():
             use_global_interceptors(*interceptors)
 
@@ -173,11 +187,13 @@ def request_context(
         send: TSend = constants.empty_send,
     ) -> HttpRequestConnectionContext:
         """
-        Create an RequestContext during request and provides instance for `current_connection`.
-        e.g
+        Creates a RequestContext during a request and provides an instance for `current_connection`.
 
+        Example:
+        ```python
         request = current_connection.switch_http_connection().get_request()
         websocket = current_connection.switch_to_websocket().get_client()
+        ```
         """
         context_factory = self.injector.get(IHostContextFactory)
         return HttpRequestConnectionContext(
@@ -226,6 +242,14 @@ async def enable_versioning(
         default_version: t.Optional[str] = None,
         **init_kwargs: t.Any,
     ) -> None:
+        """
+        Enables API versioning for the application.
+
+        :param schema: Versioning scheme to use.
+        :param version_parameter: Parameter name for versioning.
+        :param default_version: Default version if none specified.
+        :param init_kwargs: Additional arguments for the versioning scheme.
+        """
         async with self.with_injector_context():
             enable_versioning(
                 schema,
@@ -262,6 +286,11 @@ async def add_exception_handler(
         self,
         *exception_handlers: IExceptionHandler,
     ) -> None:
+        """
+        Registers global exception handlers.
+
+        :param exception_handlers: Exception handlers to register.
+        """
         async with self.with_injector_context():
             use_exception_handler(*exception_handlers)
 
@@ -274,6 +303,11 @@ def reflector(self) -> Reflector:
     async def add_authentication_schemes(
         self, *authentication: AuthenticationHandlerType
     ) -> None:
+        """
+        Registers authentication schemes for the application.
+
+        :param authentication: Authentication schemes to register.
+        """
         async with self.with_injector_context():
             use_authentication_schemes(*authentication)
 
@@ -319,7 +353,11 @@ def url_for(context: t.Dict, name: str, **path_params: t.Any) -> URL:
         return jinja_env
 
     def setup_jinja_environment(self) -> Environment:
-        """Sets up Jinja2 Environment and adds it to DI"""
+        """
+        Sets up the Jinja2 Environment and adds it to the dependency injection container.
+
+        :return: Configured Jinja2 Environment.
+        """
         jinja_environment = self._create_jinja_environment()
 
         self.injector.tree_manager.get_app_module().add_provider(