updated doc strings

docforge/models/__init__.py

@@ -1,17 +1,28 @@
 """
-# Model Layer
+Model layer for doc-forge.
 
-The `docforge.models` package provides the core data structures used to represent
-Python source code in a documentation-focused hierarchy.
+The ``docforge.models`` package defines the core data structures used to
+represent Python source code as a structured documentation model.
 
-## Key Components
+Overview
+--------
 
-- **Project**: The root container for all documented modules.
-- **Module**: Represents a Python module or package, containing members.
-- **DocObject**: A recursive structure for classes, functions, and attributes.
+The model layer forms the central intermediate representation used throughout
+doc-forge. Python modules and objects discovered during introspection are
+converted into a hierarchy of documentation models that can later be rendered
+into different documentation formats.
 
-These classes are designed to be renderer-agnostic, allowing the same internal
-representation to be transformed into various output formats (currently MkDocs).
+Key components:
+
+- **Project** – Root container representing an entire documented codebase.
+- **Module** – Representation of a Python module or package containing
+  documented members.
+- **DocObject** – Recursive structure representing Python objects such as
+  classes, functions, methods, and attributes.
+
+These models are intentionally **renderer-agnostic**, allowing the same
+documentation structure to be transformed into multiple output formats
+(e.g., MkDocs, MCP, or other renderers).
 """
 
 from .project import Project

docforge/models/module.py

@@ -1,7 +1,10 @@
 """
-This module defines the Module class, which represents a Python module or package
-in the doc-forge documentation models. It acts as a container for top-level
-documented objects.
+Documentation model representing a Python module or package.
+
+This module defines the ``Module`` class used in the doc-forge documentation
+model. A ``Module`` acts as a container for top-level documented objects
+(classes, functions, variables, and other members) discovered during
+introspection.
 """
 
 from typing import Dict, Iterable, Optional
@@ -11,12 +14,17 @@ from docforge.models.object import DocObject
 
 class Module:
     """
-    Represents a documented Python module or package.
+    Representation of a documented Python module or package.
+
+    A ``Module`` stores metadata about the module itself and maintains a
+    collection of top-level documentation objects discovered during
+    introspection.
 
     Attributes:
         path: Dotted import path of the module.
-        docstring: Module-level docstring content.
-        members: Dictionary mapping object names to their DocObject representations.
+        docstring: Module-level documentation string, if present.
+        members: Mapping of object names to their corresponding
+            ``DocObject`` representations.
     """
 
     def __init__(
@@ -25,11 +33,11 @@ class Module:
         docstring: Optional[str] = None,
     ) -> None:
         """
-        Initialize a new Module.
+        Initialize a Module instance.
 
         Args:
-            path: The dotted path of the module.
-            docstring: The module's docstring, if any.
+            path: Dotted import path identifying the module.
+            docstring: Module-level documentation text, if available.
         """
         self.path = path
         self.docstring = docstring
@@ -40,27 +48,32 @@ class Module:
         Add a documented object to the module.
 
         Args:
-            obj: The object to add.
+            obj: Documentation object to register as a top-level
+                member of the module.
         """
         self.members[obj.name] = obj
 
     def get_object(self, name: str) -> DocObject:
         """
-        Retrieve a member object by name.
+        Retrieve a documented object by name.
 
         Args:
-            name: The name of the object.
+            name: Name of the object to retrieve.
 
         Returns:
-            The requested DocObject.
+            The corresponding ``DocObject`` instance.
+
+        Raises:
+            KeyError: If no object with the given name exists.
         """
         return self.members[name]
 
     def get_all_objects(self) -> Iterable[DocObject]:
         """
-        Get all top-level objects in the module.
+        Return all top-level documentation objects in the module.
 
         Returns:
-            An iterable of DocObject instances.
+            An iterable of ``DocObject`` instances representing the
+            module's public members.
         """
         return self.members.values()

docforge/models/object.py

@@ -1,7 +1,10 @@
 """
-This module defines the DocObject class, the fundamental recursive unit of the
-doc-forge documentation models. A DocObject represents a single Python entity
-(class, function, method, or attribute) and its nested members.
+Documentation model representing individual Python objects.
+
+This module defines the ``DocObject`` class, the fundamental recursive unit of
+the doc-forge documentation model. Each ``DocObject`` represents a Python
+entity such as a class, function, method, or attribute, and may contain nested
+members that form a hierarchical documentation structure.
 """
 
 from typing import Dict, Iterable, Optional
@@ -9,15 +12,20 @@ from typing import Dict, Iterable, Optional
 
 class DocObject:
     """
-    Represents a documented Python object (class, function, method, etc.).
+    Representation of a documented Python object.
+
+    A ``DocObject`` models a single Python entity discovered during
+    introspection. Objects may contain nested members, allowing the structure
+    of modules, classes, and other containers to be represented recursively.
 
     Attributes:
         name: Local name of the object.
-        kind: Type of object (e.g., 'class', 'function', 'attribute').
-        path: Full dotted import path to the object.
-        signature: Callable signature, if applicable.
-        docstring: Raw docstring content extracted from the source.
-        members: Dictionary mapping member names to their DocObject representations.
+        kind: Type of object (for example ``class``, ``function``,
+            ``method``, or ``attribute``).
+        path: Fully qualified dotted path to the object.
+        signature: Callable signature if the object represents a callable.
+        docstring: Raw docstring text extracted from the source code.
+        members: Mapping of member names to child ``DocObject`` instances.
     """
 
     def __init__(
@@ -29,48 +37,54 @@ class DocObject:
         docstring: Optional[str] = None,
     ) -> None:
         """
-        Initialize a new DocObject.
+        Initialize a DocObject instance.
 
         Args:
-            name: The local name of the object.
-            kind: The kind of object (e.g., 'class', 'function').
-            path: The full dotted path to the object.
-            signature: The object's signature (for callable objects).
-            docstring: The object's docstring, if any.
+            name: Local name of the object.
+            kind: Object type identifier (for example ``class`` or ``function``).
+            path: Fully qualified dotted path of the object.
+            signature: Callable signature if applicable.
+            docstring: Documentation string associated with the object.
         """
         self.name = name
         self.kind = kind
         self.path = path
         self.signature = signature
         self.docstring = docstring
-        self.members: Dict[str, 'DocObject'] = {}
+        self.members: Dict[str, "DocObject"] = {}
 
-    def add_member(self, obj: 'DocObject') -> None:
+    def add_member(self, obj: "DocObject") -> None:
         """
-        Add a child member to this object (e.g., a method to a class).
+        Add a child documentation object.
+
+        This is typically used when attaching methods to classes or
+        nested objects to their parent containers.
 
         Args:
-            obj: The child DocObject to add.
+            obj: Documentation object to add as a member.
         """
         self.members[obj.name] = obj
 
-    def get_member(self, name: str) -> 'DocObject':
+    def get_member(self, name: str) -> "DocObject":
         """
-        Retrieve a child member by name.
+        Retrieve a member object by name.
 
         Args:
-            name: The name of the member.
+            name: Name of the member to retrieve.
 
         Returns:
-            The requested DocObject.
+            The corresponding ``DocObject`` instance.
+
+        Raises:
+            KeyError: If the member does not exist.
         """
         return self.members[name]
 
-    def get_all_members(self) -> Iterable['DocObject']:
+    def get_all_members(self) -> Iterable["DocObject"]:
         """
-        Get all members of this object.
+        Return all child members of the object.
 
         Returns:
-            An iterable of child DocObject instances.
+            An iterable of ``DocObject`` instances representing nested members.
         """
         return self.members.values()

docforge/models/project.py

@@ -1,6 +1,9 @@
 """
-This module defines the Project class, the top-level container for a documented
-project. It aggregates multiple Module instances into a single named entity.
+Documentation model representing a project.
+
+This module defines the ``Project`` class, the top-level container used by
+doc-forge to represent a documented codebase. A ``Project`` aggregates multiple
+modules and provides access to them through a unified interface.
 """
 
 from typing import Dict, Iterable
@@ -10,29 +13,32 @@ from docforge.models.module import Module
 
 class Project:
     """
-    Represents a documentation project, serving as a container for modules.
+    Representation of a documentation project.
+
+    A ``Project`` serves as the root container for all modules discovered during
+    introspection. Each module is stored by its dotted import path.
 
     Attributes:
         name: Name of the project.
-        modules: Dictionary mapping module paths to Module instances.
+        modules: Mapping of module paths to ``Module`` instances.
     """
 
     def __init__(self, name: str) -> None:
         """
-        Initialize a new Project.
+        Initialize a Project instance.
 
         Args:
-            name: The name of the project.
+            name: Name used to identify the documentation project.
         """
         self.name = name
         self.modules: Dict[str, Module] = {}
 
     def add_module(self, module: Module) -> None:
         """
-        Add a module to the project.
+        Register a module in the project.
 
         Args:
-            module: The module to add.
+            module: Module instance to add to the project.
         """
         self.modules[module.path] = module
 
@@ -41,27 +47,30 @@ class Project:
         Retrieve a module by its dotted path.
 
         Args:
-            path: The dotted path of the module (e.g., 'pkg.mod').
+            path: Fully qualified dotted module path (for example ``pkg.module``).
 
         Returns:
-            The requested Module.
+            The corresponding ``Module`` instance.
+
+        Raises:
+            KeyError: If the module does not exist in the project.
         """
         return self.modules[path]
 
     def get_all_modules(self) -> Iterable[Module]:
         """
-        Get all modules in the project.
+        Return all modules contained in the project.
 
         Returns:
-            An iterable of Module objects.
+            An iterable of ``Module`` instances.
         """
         return self.modules.values()
 
     def get_module_list(self) -> list[str]:
         """
-        Get the list of all module dotted paths.
+        Return the list of module import paths.
 
         Returns:
-            A list of module paths.
+            A list containing the dotted paths of all modules in the project.
         """
-        return list(self.modules.keys())
+        return list(self.modules.keys())