updated doc strings

docforge/loaders/griffe_loader.py

@@ -1,6 +1,9 @@
 """
-This module provides the GriffeLoader, which uses the 'griffe' library to
-introspect Python source code and populate the doc-forge Project models.
+Utilities for loading and introspecting Python modules using Griffe.
+
+This module provides the ``GriffeLoader`` class and helper utilities used to
+discover Python modules, introspect their structure, and convert the results
+into doc-forge documentation models.
 """
 
 import logging
@@ -25,19 +28,27 @@ def discover_module_paths(
     project_root: Path | None = None,
 ) -> List[str]:
     """
-    Discover all Python modules under a package via filesystem traversal.
+    Discover Python modules within a package directory.
 
-    Rules:
-    - Directory with __init__.py is treated as a package.
-    - Any .py file is treated as a module.
-    - All paths are converted to dotted module paths.
+    The function scans the filesystem for ``.py`` files inside the specified
+    package and converts them into dotted module import paths.
+
+    Discovery rules:
+
+    - Directories containing ``__init__.py`` are treated as packages.
+    - Each ``.py`` file is treated as a module.
+    - Results are returned as dotted import paths.
 
     Args:
-        module_name: The name of the package to discover.
-        project_root: The root directory of the project. Defaults to current working directory.
+        module_name: Top-level package name to discover modules from.
+        project_root: Root directory used to resolve module paths. If not
+            provided, the current working directory is used.
 
     Returns:
-        A sorted list of dotted module paths.
+        A sorted list of unique dotted module import paths.
+
+    Raises:
+        FileNotFoundError: If the specified package directory does not exist.
     """
 
     if project_root is None:
@@ -64,12 +75,19 @@ def discover_module_paths(
 
 class GriffeLoader:
     """
-    Loads Python modules and extracts documentation using the Griffe introspection engine.
+    Load Python modules using Griffe and convert them into doc-forge models.
+
+    This loader uses the Griffe introspection engine to analyze Python source
+    code and transform the extracted information into ``Project``, ``Module``,
+    and ``DocObject`` instances used by doc-forge.
     """
 
     def __init__(self) -> None:
         """
-        Initialize the GriffeLoader.
+        Initialize the Griffe-backed loader.
+
+        Creates an internal Griffe loader instance with dedicated collections
+        for modules and source lines.
         """
         self._loader = _GriffeLoader(
             modules_collection=ModulesCollection(),
@@ -77,21 +95,32 @@ class GriffeLoader:
         )
 
     def load_project(
-        self,
-        module_paths: List[str],
-        project_name: Optional[str] = None,
-        skip_import_errors: bool = None,
+            self,
+            module_paths: List[str],
+            project_name: Optional[str] = None,
+            skip_import_errors: bool = None,
     ) -> Project:
         """
-        Load multiple modules and combine them into a single Project models.
+        Load multiple modules and assemble them into a Project model.
+
+        Each module path is introspected and converted into a ``Module``
+        instance. All modules are then aggregated into a single ``Project``
+        object.
 
         Args:
-            module_paths: A list of dotted paths to the modules to load.
-            project_name: Optional name for the project. Defaults to the first module name.
-            skip_import_errors: If True, modules that fail to import will be skipped.
+            module_paths: List of dotted module import paths to load.
+            project_name: Optional override for the project name. Defaults
+                to the top-level name of the first module.
+            skip_import_errors: If True, modules that fail to load will be
+                skipped instead of raising an error.
 
         Returns:
-            A Project instance containing the loaded modules.
+            A populated ``Project`` instance containing the loaded modules.
+
+        Raises:
+            ValueError: If no module paths are provided.
+            ImportError: If a module fails to load and
+                ``skip_import_errors`` is False.
         """
         if not module_paths:
             raise ValueError("At least one module path must be provided")
@@ -116,13 +145,16 @@ class GriffeLoader:
 
     def load_module(self, path: str) -> Module:
         """
-        Load a single module and convert its introspection data into the docforge models.
+        Load and convert a single Python module.
+
+        The module is introspected using Griffe and then transformed into
+        a doc-forge ``Module`` model.
 
         Args:
-            path: The dotted path of the module to load.
+            path: Dotted import path of the module.
 
         Returns:
-            A Module instance.
+            A populated ``Module`` instance.
         """
         self._loader.load(path)
         griffe_module = self._loader.modules_collection[path]
@@ -135,13 +167,16 @@ class GriffeLoader:
 
     def _convert_module(self, obj: Object) -> Module:
         """
-        Convert a Griffe Object (module) into a docforge Module.
+        Convert a Griffe module object into a doc-forge Module.
+
+        All public members of the module are recursively converted into
+        ``DocObject`` instances.
 
         Args:
-            obj: The Griffe Object representing the module.
+            obj: Griffe object representing the module.
 
         Returns:
-            A populated Module instance.
+            A populated ``Module`` model.
         """
         module = Module(
             path=obj.path,
@@ -158,13 +193,17 @@ class GriffeLoader:
 
     def _convert_object(self, obj: Object) -> DocObject:
         """
-        Recursively convert a Griffe Object into a DocObject hierarchy.
+        Convert a Griffe object into a doc-forge DocObject.
+
+        The conversion preserves the object's metadata such as name,
+        kind, path, signature, and docstring. Child members are processed
+        recursively.
 
         Args:
-            obj: The Griffe Object to convert.
+            obj: Griffe object representing a documented Python object.
 
         Returns:
-            A DocObject instance.
+            A ``DocObject`` instance representing the converted object.
         """
         kind = obj.kind.value
         signature = self._safe_signature(obj)
@@ -193,13 +232,13 @@ class GriffeLoader:
 
     def _safe_docstring(self, obj: Object) -> Optional[str]:
         """
-        Safely retrieve the docstring value from a Griffe object.
+        Safely extract a docstring from a Griffe object.
 
         Args:
-            obj: The Griffe Object to inspect.
+            obj: Griffe object to inspect.
 
         Returns:
-            The raw docstring string, or None if missing or unresolvable.
+            The raw docstring text if available, otherwise ``None``.
         """
         try:
             return obj.docstring.value if obj.docstring else None
@@ -208,13 +247,14 @@ class GriffeLoader:
 
     def _safe_signature(self, obj: Object) -> Optional[str]:
         """
-        Safely retrieve the signature string from a Griffe object.
+        Safely extract the signature of a Griffe object.
 
         Args:
-            obj: The Griffe Object to inspect.
+            obj: Griffe object to inspect.
 
         Returns:
-            The string representation of the signature, or None.
+            String representation of the object's signature if available,
+            otherwise ``None``.
         """
         try:
             if hasattr(obj, "signature") and obj.signature: