google styled doc string

docforge/__init__.py

@@ -135,122 +135,122 @@ Models:
 
 ## Google-Styled Doc-Forge Convention (GSDFC)
 
-GSDFC defines how docstrings must be written so they render correctly in MkDocs
+GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
-and remain machine-parsable.
 
-Docstrings are the single source of truth. doc-forge compiles docstrings but does
+- Docstrings are the single source of truth.
-not generate documentation content.
+- doc-forge compiles docstrings but does not generate documentation content.
-
+- Documentation follows the Python import hierarchy.
-Documentation follows the Python import hierarchy.
+- Every public symbol should have a complete and accurate docstring.
 
 ---
 
 ### General rules
 
-Use Markdown headings at package and module level.
+- Use **Markdown headings** at package and module level.
-
+- Use **Google-style structured sections** at class, function, and method level.
-Use Google-style sections at class and function level.
+- Indent section contents using four spaces.
-
+- Use type hints in signatures instead of duplicating types in prose.
-Supported structured sections:
+- Write summaries in imperative form.
-
+- Sections are separated by ```---```
-    Args:
-    Returns:
-    Raises:
-    Yields:
-    Attributes:
-    Notes:
-    Example:
-    Examples:
-    See Also:
-
-Indent section contents using four spaces.
-
-Type information must come from function signatures, not duplicated prose.
-
-Avoid NumPy-style sections such as:
-
-    Parameters
-    Returns tables
-
-Avoid pseudo-fields such as:
-
-    required:
-    default:
 
 ---
 
 ### Package docstrings
 
-Package docstrings act as the documentation home page.
+- Package docstrings act as the documentation home page.
 
-They should include:
+Recommended sections:
 
-    Summary
+    ## Summary
-    ---
+    ## Installation
-    Installation
+    ## Quick start
-    Quick start
+    ## Core concepts
-    Core concepts
+    ## Architecture
-    Architecture
+    ## Rendering pipeline
-    Rendering pipeline
+    ## CLI usage
-    CLI usage
+    ## Public API
-    Public API
+    ## Examples
-    Examples
+    ## Notes
-    Notes
 
 Example:
+    Package Doc String:
 
         '''
-    My package summary.
+        Foo-bar processing framework.
+
+        Provides tools for defining Foo objects and executing Bar pipelines.
 
         ---
 
         ## Installation
 
-        pip install my-package
+            pip install foo-bar
+
+        ---
 
         ## Quick start
 
-        from my_package import Foo
+            from foobar import Foo, BarEngine
 
-        foo = Foo()
+            foo = Foo("example")
-        foo.run()
+            engine = BarEngine([foo])
+
+            result = engine.run()
+
+        ---
+
+        ## Public API
+
+            Foo
+            Bar
+            BarEngine
+
+        ---
         '''
 
 ---
 
 ### Module docstrings
 
-Module docstrings describe subsystems.
+- Module docstrings describe a subsystem.
 
 Recommended sections:
 
-    Summary
+    ## Summary
-    ---
+    ## Examples
-    Examples
+    ## Notes
-    Notes
+    ## Public API
-    Public API
 
 Example:
+    Module Doc String:
 
         '''
-    Execution subsystem.
+        Foo execution subsystem.
+
+        Provides utilities for executing Foo objects through Bar stages.
 
         ---
 
         Example:
 
-        from my_package.engine import Engine
+            from foobar.engine import BarEngine
+            from foobar.foo import Foo
 
-        engine = Engine(nodes)
+            foo = Foo("example")
+
+            engine = BarEngine([foo])
+            engine.run()
+
+        ---
         '''
 
 ---
 
 ### Class docstrings
 
-Class docstrings define object responsibility and lifecycle.
+- Class docstrings define object responsibility, lifecycle, and attributes.
 
-Supported sections:
+Recommended sections:
 
     Attributes:
     Notes:
@@ -258,39 +258,68 @@ Supported sections:
     Raises:
 
 Example:
+    Simple Foo:
 
-    class Engine:
+        class Foo:
             '''
-        Executes pipelines.
+            Represents a unit of work.
 
             Attributes:
-            nodes (tuple[Node, ...]):
+                name (str):
-                Execution nodes.
+                    Identifier of the foo instance.
+
+                value (int):
+                    Numeric value associated with foo.
 
             Notes:
                 Guarantees:
 
-                - deterministic execution
+                    - instances are immutable after creation
-                - immutable state propagation
 
                 Lifecycle:
 
-                - reusable across executions
+                    - create instance
+                    - pass to processing engine
 
             Example:
-            Basic usage:
+                Create and inspect a Foo:
 
-                engine = Engine(nodes)
+                    foo = Foo("example", value=42)
-                engine.run(state)
+                    print(foo.name)
+            '''
+
+    Complex Bar:
+
+        class BarEngine:
+            '''
+            Executes Foo objects through Bar stages.
+
+            Attributes:
+                foos (tuple[Foo, ...]):
+                    Foo instances managed by the engine.
+
+            Notes:
+                Guarantees:
+
+                    - deterministic execution order
+
+            Example:
+                Run engine:
+
+                    foo1 = Foo("a")
+                    foo2 = Foo("b")
+
+                    engine = BarEngine([foo1, foo2])
+                    engine.run()
             '''
 
 ---
 
 ### Function and method docstrings
 
-Function docstrings define API contracts.
+- Function docstrings define API contracts.
 
-Supported sections:
+Recommended sections:
 
     Args:
     Returns:
@@ -300,112 +329,184 @@ Supported sections:
     Example:
 
 Example:
+    Simple process method:
 
-    def run(state: State) -> list[State]:
+        def process(foo: Foo, multiplier: int) -> int:
             '''
-        Execute pipeline.
+            Process a Foo instance.
 
             Args:
-            state (State):
+                foo (Foo):
-                Initial execution state.
+                    Foo instance to process.
+
+                multiplier (int):
+                    Value used to scale foo.
 
             Returns:
-            list[State]:
+                int:
-                Resulting execution states.
+                    Processed result.
+
+            Raises:
+                ValueError:
+                    If multiplier is negative.
 
             Notes:
                 Guarantees:
 
-                - state is not modified
+                    - foo is not modified
+
+            Example:
+                Process foo:
+
+                    foo = Foo("example", value=10)
+
+                    result = process(foo, multiplier=2)
+                    print(result)
+            '''
+
+    Multiple Examples:
+
+        def combine(foo_a: Foo, foo_b: Foo) -> Foo:
+            '''
+            Combine two Foo instances.
+
+            Args:
+                foo_a (Foo):
+                    First foo.
+
+                foo_b (Foo):
+                    Second foo.
+
+            Returns:
+                Foo:
+                    Combined foo.
+
+            Example:
+                Basic usage:
+
+                    foo1 = Foo("a")
+                    foo2 = Foo("b")
+
+                    combined = combine(foo1, foo2)
+
+                Pipeline usage:
+
+                    engine = BarEngine([foo1, foo2])
+                    engine.run()
             '''
 
 ---
 
 ### Property docstrings
 
-Properties must document return values.
+- Properties must document return values.
 
 Example:
 
-    @property
+    class FooContainer:
-    def nodes(self) -> tuple[Node, ...]:
         '''
-        Return execution nodes.
+        Container for Foo objects.
+        '''
+
+        @property
+        def foos(self) -> tuple[Foo, ...]:
+            '''
+            Return contained Foo instances.
 
             Returns:
-            tuple[Node, ...]:
+                tuple[Foo, ...]:
-                Configured nodes.
+                    Stored foo objects.
+
+            Example:
+                container = FooContainer()
+
+                foos = container.foos
             '''
 
 ---
 
 ### Attribute documentation
 
-Attributes must be documented in the class docstring using Attributes:.
+- Document attributes in class docstrings using Attributes:.
 
 Example:
 
-    class State:
+    class Bar:
         '''
-        Execution state.
+        Represents a processing stage.
 
         Attributes:
-            payload (dict):
+            id (str):
-                Immutable execution data.
+                Unique identifier.
 
-            depth (int):
+            enabled (bool):
-                Distance from root state.
+                Whether the stage is active.
         '''
 
 ---
 
 ### Notes subsection grouping
 
-Subsections may be grouped using labeled blocks:
+- Group related information using labeled subsections.
+
+Example:
 
     Notes:
-        Guarantees:
+        **Guarantees:**
 
-            - deterministic execution
+            - deterministic behavior
 
-        Lifecycle:
+        **Lifecycle:**
 
-            - reusable instance
+            - created during initialization
+            - reused across executions
 
-        Thread safety:
+        **Thread safety:**
 
-            - safe for concurrent use
+            - safe for concurrent reads
-
-Do not use horizontal separators inside structured sections.
 
 ---
 
 ### Example formatting
 
-Use indentation for examples:
+- Use indentation for examples.
+
+Single example:
 
     Example:
-        Basic usage:
 
-            engine = Engine(nodes)
+        foo = Foo("example")
-            engine.run(state)
+        process(foo, multiplier=2)
 
-Multiple examples may be grouped using labels.
+Multiple examples:
+
+    Example:
+        Create foo:
+
+            foo = Foo("example")
+
+        Run engine:
+
+            engine = BarEngine([foo])
+            engine.run()
+
+Avoid fenced code blocks inside structured sections.
 
 ---
 
 ### Separator rules
 
-Use horizontal separators only at docstring root level:
+Use horizontal separators only at docstring root level to separate sections:
 
     ---
 
-Do not use separators inside:
+Allowed locations:
 
-    Args:
+- package docstrings
-    Returns:
+- module docstrings
-    Notes:
+- major documentation sections
-    Attributes:
+
+Do not use separators inside code sections.
 
 ---
 
@@ -413,15 +514,19 @@ Do not use separators inside:
 
 GSDFC ensures doc-forge can deterministically extract:
 
-    symbol type
+- symbol kind (module, class, function, property, attribute)
-    symbol name
+- symbol name
-    parameters
+- parameters
-    return types
+- return values
-    attributes
+- attributes
-    examples
+- examples
-    structured notes
+- structured Notes subsections
 
-This enables reliable MkDocs rendering and MCP export.
+This enables:
+
+- reliable MkDocs rendering
+- deterministic MCP export
+- accurate AI semantic interpretation
 
 ---