@alloy-js/python 0.2.0-dev.3 → 0.2.0-dev.5

package/dist/test/pydocs.test.js

@@ -4,7 +4,7 @@ import { d } from "@alloy-js/core/testing";
 import { describe, expect, it } from "vitest";
 import { enumModule } from "../src/builtins/python.js";
 import * as py from "../src/index.js";
-import { toSourceText } from "./utils.js";
+import { assertFileContents, toSourceText, toSourceTextMultiple } from "./utils.js";
 describe("PyDoc", () => {
   it("formats properly", () => {
     const res = toSourceText([_$createComponent(py.PyDoc, {
@@ -120,161 +120,645 @@ describe("PyDocExample", () => {
       `);
   });
 });
-describe("GoogleStyleDocParam", () => {
-  it("name only", () => {
-    const res = toSourceText([_$createComponent(py.PyDoc, {
+describe("SimpleCommentBlock", () => {
+  it("renders simple comment block", () => {
+    const res = toSourceText([_$createComponent(py.SimpleCommentBlock, {
+      children: "This is a simple comment block that spans multiple lines."
+    })]);
+    expect(res).toRenderTo(d`
+          # This is a simple comment block that spans multiple lines.
+          
+          `);
+  });
+  it("renders comment block with line breaks", () => {
+    const res = toSourceText([_$createComponent(py.SimpleCommentBlock, {
       get children() {
-        return _$createComponent(py.GoogleStyleDocParam, {
-          name: "somebody"
-        });
+        return ["First line of comment.", _$createIntrinsic("br", {}), "Second line of comment."];
       }
     })]);
     expect(res).toRenderTo(d`
-          """
-          somebody
-          """
+          # First line of comment. Second line of comment.
+          
+          `);
+  });
+});
+describe("SimpleInlineComment", () => {
+  it("renders inline comment", () => {
+    const res = toSourceText([["x = 42", _$createComponent(py.SimpleInlineComment, {
+      children: "This is an inline comment"
+    })]]);
+    expect(res).toRenderTo(d`
+          x = 42  # This is an inline comment
+          `);
+  });
+  it("renders inline comment with complex text", () => {
+    const res = toSourceText([["result = calculate()", _$createComponent(py.SimpleInlineComment, {
+      children: "TODO: Add error handling here"
+    })]]);
+    expect(res).toRenderTo(d`
+          result = calculate()  # TODO: Add error handling here
+          `);
+  });
+});
+describe("SimpleInlineMemberComment", () => {
+  it("renders inline member comment", () => {
+    const res = toSourceText([["status: int", _$createComponent(py.SimpleInlineMemberComment, {
+      children: "HTTP status code"
+    })]]);
+    expect(res).toRenderTo(d`
+          status: int  #: HTTP status code
+          `);
+  });
+  it("renders inline member comment for variable declaration", () => {
+    const res = toSourceText([["max_retries = 3", _$createComponent(py.SimpleInlineMemberComment, {
+      children: "Maximum number of retry attempts"
+    })]]);
+    expect(res).toRenderTo(d`
+          max_retries = 3  #: Maximum number of retry attempts
+          `);
+  });
+});
+describe("New Documentation Components", () => {
+  it("ModuleDoc renders correctly", () => {
+    const res = toSourceText([_$createComponent(py.ModuleDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "This module demonstrates documentation as specified by the Google Python Style Guide."
+        })];
+      },
+      attributes: [{
+        name: "module_level_variable1",
+        type: "int",
+        children: "Module level variables may be documented."
+      }],
+      get examples() {
+        return [_$createComponent(py.PyDocExample, {
+          children: "print(\"mod\")"
+        })];
+      },
+      seeAlso: ["another_module.func", "RelatedClass"],
+      warning: "Internal API.",
+      deprecated: "Use new_module instead.",
+      todo: ["For module TODOs", "You have to also use sphinx.ext.todo extension"]
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        This module demonstrates documentation as specified by the Google Python Style
+        Guide.
 
+        Attributes:
+            module_level_variable1 (int): Module level variables may be documented.
 
-          `);
+        Examples:
+            >> print("mod")
+
+        See Also:
+            another_module.func
+            RelatedClass
+
+        Warning:
+            Internal API.
+
+        Deprecated:
+            Use new_module instead.
+
+        Todo:
+            * For module TODOs
+            * You have to also use sphinx.ext.todo extension
+        """
+
+
+        `);
   });
-  it("name and type", () => {
-    const res = toSourceText([_$createComponent(py.PyDoc, {
-      get children() {
-        return _$createComponent(py.GoogleStyleDocParam, {
-          name: "somebody",
-          type: "str"
-        });
-      }
+  it("PropertyDoc renders correctly", () => {
+    const res = toSourceText([_$createComponent(py.PropertyDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Properties should be documented in their getter method."
+        })];
+      },
+      returns: "str: The readonly property value.",
+      get examples() {
+        return [_$createComponent(py.PyDocExample, {
+          children: "print(obj.name)"
+        })];
+      },
+      seeAlso: ["other_property"],
+      warning: "Access may be slow.",
+      deprecated: "Use full_name instead.",
+      note: "If the setter method contains notable behavior, it should be mentioned here."
     })]);
     expect(res).toRenderTo(d`
-          """
-          somebody (str)
-          """
+        """
+        Properties should be documented in their getter method.
 
+        Returns:
+            str: The readonly property value.
 
-          `);
+        Examples:
+            >> print(obj.name)
+
+        See Also:
+            other_property
+
+        Warning:
+            Access may be slow.
+
+        Deprecated:
+            Use full_name instead.
+
+        Note:
+            If the setter method contains notable behavior, it should be mentioned here.
+        """
+
+
+        `);
   });
-  it("name, type and description", () => {
-    const res = toSourceText([_$createComponent(py.PyDoc, {
-      get children() {
-        return _$createComponent(py.GoogleStyleDocParam, {
-          name: "somebody",
-          type: "str",
-          children: "Somebody's name."
-        });
-      }
+  it("GeneratorDoc renders correctly", () => {
+    const res = toSourceText([_$createComponent(py.GeneratorDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Generators have a Yields section instead of a Returns section."
+        })];
+      },
+      parameters: [{
+        name: "n",
+        type: "int",
+        doc: "The upper limit of the range to generate, from 0 to n - 1."
+      }],
+      yields: "int: The next number in the range of 0 to n - 1.",
+      get examples() {
+        return [_$createComponent(py.PyDocExample, {
+          children: "print(next(gen))"
+        })];
+      },
+      seeAlso: ["make_generator"],
+      warning: "Do not consume in tight loops without sleep.",
+      deprecated: "Use new_generator instead.",
+      note: "Examples should be written in doctest format."
     })]);
     expect(res).toRenderTo(d`
-          """
-          somebody (str): Somebody's name.
-          """
+        """
+        Generators have a Yields section instead of a Returns section.
 
+        Args:
+            n (int): The upper limit of the range to generate, from 0 to n - 1.
 
-          `);
+        Yields:
+            int: The next number in the range of 0 to n - 1.
+
+        Examples:
+            >> print(next(gen))
+
+        See Also:
+            make_generator
+
+        Warning:
+            Do not consume in tight loops without sleep.
+
+        Deprecated:
+            Use new_generator instead.
+
+        Note:
+            Examples should be written in doctest format.
+        """
+
+
+        `);
   });
-  it("name, type, description, and optional", () => {
-    const res = toSourceText([_$createComponent(py.PyDoc, {
-      get children() {
-        return _$createComponent(py.GoogleStyleDocParam, {
-          name: "somebody",
-          type: "str",
-          optional: true,
-          children: "Somebody's name."
-        });
-      }
+  it("ExceptionDoc renders correctly", () => {
+    const res = toSourceText([_$createComponent(py.ExceptionDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Exceptions are documented in the same way as classes."
+        })];
+      },
+      parameters: [{
+        name: "msg",
+        type: "str",
+        doc: "Human readable string describing the exception."
+      }, {
+        name: "code",
+        type: "int",
+        default: undefined,
+        doc: "Error code."
+      }],
+      attributes: [{
+        name: "msg",
+        type: "str",
+        children: "Human readable string describing the exception."
+      }, {
+        name: "code",
+        type: "int",
+        children: "Exception error code."
+      }],
+      seeAlso: ["BaseException"],
+      deprecated: "Use NewException instead.",
+      note: "Do not include the 'self' parameter in the Args section."
     })]);
     expect(res).toRenderTo(d`
-          """
-          somebody (str, optional): Somebody's name.
-          """
+        """
+        Exceptions are documented in the same way as classes.
 
+        Args:
+            msg (str): Human readable string describing the exception.
 
-          `);
+            code (int): Error code.
+
+        Attributes:
+            msg (str): Human readable string describing the exception.
+
+            code (int): Exception error code.
+
+        See Also:
+            BaseException
+
+        Deprecated:
+            Use NewException instead.
+
+        Note:
+            Do not include the 'self' parameter in the Args section.
+        """
+
+
+        `);
   });
-  it("name, type, description, and optional with default value", () => {
-    const res = toSourceText([_$createComponent(py.PyDoc, {
-      get children() {
-        return _$createComponent(py.GoogleStyleDocParam, {
-          name: "somebody",
-          type: "str",
-          optional: true,
-          defaultValue: "John Doe",
-          children: "Somebody's name."
-        });
-      }
+  it("MethodDoc renders correctly without default note", () => {
+    const res = toSourceText([_$createComponent(py.MethodDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Class methods are similar to regular functions."
+        })];
+      },
+      parameters: [{
+        name: "param1",
+        doc: "The first parameter."
+      }, {
+        name: "param2",
+        doc: "The second parameter."
+      }],
+      returns: "True if successful, False otherwise.",
+      overrides: "Base.method"
     })]);
     expect(res).toRenderTo(d`
         """
-        somebody (str, optional): Somebody's name. Defaults to \"John Doe\".
+        Class methods are similar to regular functions.
+
+        Args:
+            param1: The first parameter.
+
+            param2: The second parameter.
+
+        Returns:
+            True if successful, False otherwise.
+
+        Overrides:
+            Base.method
         """
 
 
         `);
   });
-  it("name, type, description, and optional with default value with a very long description", () => {
-    const res = toSourceText([_$createComponent(py.PyDoc, {
-      get children() {
-        return [_$createComponent(py.GoogleStyleDocParam, {
-          name: "somebody",
-          type: "str",
-          optional: true,
-          defaultValue: "John Doe",
-          children: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., \"Agent X\"). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller."
-        }), _$createComponent(py.GoogleStyleDocParam, {
-          name: "somebody2",
-          type: "str",
-          children: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., \"Agent X\"). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller."
+  it("MethodDoc renders correctly with custom note", () => {
+    const res = toSourceText([_$createComponent(py.MethodDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Class methods are similar to regular functions."
+        })];
+      },
+      parameters: [{
+        name: "param1",
+        doc: "The first parameter."
+      }],
+      returns: "True if successful, False otherwise.",
+      note: "This method has special behavior when called multiple times."
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Class methods are similar to regular functions.
+
+        Args:
+            param1: The first parameter.
+
+        Returns:
+            True if successful, False otherwise.
+
+        Note:
+            This method has special behavior when called multiple times.
+        """
+
+
+        `);
+  });
+  it("ModuleDoc with minimal content", () => {
+    const res = toSourceText([_$createComponent(py.ModuleDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Simple module description."
         })];
       }
-    })], {
-      printOptions: {
-        printWidth: 80
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Simple module description.
+        """
+
+
+        `);
+  });
+  it("ModuleDoc with only todo items", () => {
+    const res = toSourceText([_$createComponent(py.ModuleDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Module with pending tasks."
+        })];
+      },
+      todo: ["Implement feature X", "Add more tests", "Update documentation"]
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Module with pending tasks.
+
+        Todo:
+            * Implement feature X
+            * Add more tests
+            * Update documentation
+        """
+
+
+        `);
+  });
+  it("PropertyDoc minimal (description only)", () => {
+    const res = toSourceText([_$createComponent(py.PropertyDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A simple readonly property."
+        })];
       }
-    });
+    })]);
     expect(res).toRenderTo(d`
-          """
-          somebody (str, optional): Somebody's name. This can be any string representing a
-              person, whether it's a first name, full name, nickname, or even a codename
-              (e.g., "Agent X"). It's used primarily for display purposes, logging, or
-              greeting messages and is not required to be unique or validated unless
-              specified by the caller. Defaults to \"John Doe\".
-          
-          somebody2 (str): Somebody's name. This can be any string representing a person,
-              whether it's a first name, full name, nickname, or even a codename (e.g.,
-              "Agent X"). It's used primarily for display purposes, logging, or greeting
-              messages and is not required to be unique or validated unless specified by
-              the caller.
-          """
+        """
+        A simple readonly property.
+        """
 
 
-          `);
+        `);
+  });
+  it("PropertyDoc with getter and setter info", () => {
+    const res = toSourceText([_$createComponent(py.PropertyDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Properties with both a getter and setter should only be documented in their getter method."
+        })];
+      },
+      returns: ":obj:`list` of :obj:`str`: The property value.",
+      note: "If the setter method contains notable behavior, it should be mentioned here."
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Properties with both a getter and setter should only be documented in their
+        getter method.
+
+        Returns:
+            :obj:\`list\` of :obj:\`str\`: The property value.
+
+        Note:
+            If the setter method contains notable behavior, it should be mentioned here.
+        """
+
+
+        `);
+  });
+  it("GeneratorDoc with complex parameters", () => {
+    const res = toSourceText([_$createComponent(py.GeneratorDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A more complex generator example with multiple parameters."
+        })];
+      },
+      parameters: [{
+        name: "start",
+        type: "int",
+        default: "0",
+        doc: "Starting value for the sequence."
+      }, {
+        name: "stop",
+        type: "int",
+        doc: "Ending value for the sequence (exclusive)."
+      }, {
+        name: "step",
+        type: "int",
+        default: "1",
+        doc: "Step size between values."
+      }],
+      yields: "int: The next number in the sequence.",
+      raises: ["ValueError: If step is zero.", "TypeError: If parameters are not integers."]
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        A more complex generator example with multiple parameters.
+
+        Args:
+            start (int, optional): Starting value for the sequence. Defaults to "0".
+
+            stop (int): Ending value for the sequence (exclusive).
+
+            step (int, optional): Step size between values. Defaults to "1".
+
+        Yields:
+            int: The next number in the sequence.
+
+        Raises:
+            ValueError: If step is zero.
+
+        Raises:
+            TypeError: If parameters are not integers.
+        """
+
+
+        `);
+  });
+  it("ExceptionDoc with comprehensive documentation", () => {
+    const res = toSourceText([_$createComponent(py.ExceptionDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A custom exception for authentication failures."
+        }), _$createComponent(Prose, {
+          children: "This exception is raised when authentication credentials are invalid or when authentication tokens have expired."
+        })];
+      },
+      parameters: [{
+        name: "message",
+        type: "str",
+        doc: "Human readable error message describing the authentication failure."
+      }, {
+        name: "error_code",
+        type: "int",
+        default: "401",
+        doc: "HTTP error code associated with the authentication failure."
+      }, {
+        name: "retry_after",
+        type: "int",
+        default: undefined,
+        doc: "Number of seconds to wait before retrying authentication."
+      }],
+      attributes: [{
+        name: "message",
+        type: "str",
+        children: "The error message."
+      }, {
+        name: "error_code",
+        type: "int",
+        children: "HTTP status code."
+      }, {
+        name: "retry_after",
+        type: "int",
+        children: "Retry delay in seconds, if applicable."
+      }],
+      note: "This exception should be caught and handled gracefully in production code."
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        A custom exception for authentication failures.
+
+        This exception is raised when authentication credentials are invalid or when
+        authentication tokens have expired.
+
+        Args:
+            message (str): Human readable error message describing the authentication
+                failure.
+
+            error_code (int, optional): HTTP error code associated with the
+                authentication failure. Defaults to "401".
+
+            retry_after (int): Number of seconds to wait before retrying authentication.
+
+        Attributes:
+            message (str): The error message.
+
+            error_code (int): HTTP status code.
+
+            retry_after (int): Retry delay in seconds, if applicable.
+
+        Note:
+            This exception should be caught and handled gracefully in production code.
+        """
+
+
+        `);
+  });
+  it("MethodDoc with raises but no returns", () => {
+    const res = toSourceText([_$createComponent(py.MethodDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A method that performs an action but doesn't return a value."
+        })];
+      },
+      parameters: [{
+        name: "data",
+        type: "bytes",
+        doc: "Raw data to process."
+      }],
+      raises: ["ValueError: If data is empty or invalid.", "IOError: If processing fails due to I/O issues."]
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        A method that performs an action but doesn't return a value.
+
+        Args:
+            data (bytes): Raw data to process.
+
+        Raises:
+            ValueError: If data is empty or invalid.
+
+        Raises:
+            IOError: If processing fails due to I/O issues.
+        """
+
+
+        `);
+  });
+  it("MethodDoc with no parameters", () => {
+    const res = toSourceText([_$createComponent(py.MethodDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A simple method with no parameters (except self)."
+        })];
+      },
+      returns: "bool: True if the operation was successful.",
+      note: "This is a parameterless method that only operates on instance state."
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        A simple method with no parameters (except self).
+
+        Returns:
+            bool: True if the operation was successful.
+
+        Note:
+            This is a parameterless method that only operates on instance state.
+        """
+
+
+        `);
   });
-  it("name, type, description, and optional with default value with a description containing a linebreak", () => {
+  it("AttributeDoc standalone usage", () => {
     const res = toSourceText([_$createComponent(py.PyDoc, {
       get children() {
-        return _$createComponent(py.GoogleStyleDocParam, {
-          name: "somebody",
-          type: "str",
-          optional: true,
-          defaultValue: "John Doe",
-          get children() {
-            return ["Somebody's name. This is one line", _$createIntrinsic("hbr", {}), "This is another line."];
-          }
+        return _$createComponent(py.AttributeDoc, {
+          name: "connection_timeout",
+          type: "float",
+          children: "Maximum time in seconds to wait for a connection to be established."
         });
       }
-    })], {
-      printOptions: {
-        printWidth: 80
-      }
-    });
+    })]);
     expect(res).toRenderTo(d`
-          """
-          somebody (str, optional): Somebody's name. This is one line
-              This is another line. Defaults to \"John Doe\".
-          """
+        """
+        connection_timeout (float): Maximum time in seconds to wait for a connection to
+            be established.
+        """
 
 
-          `);
+        `);
+  });
+  it("GeneratorDoc with examples in description", () => {
+    const res = toSourceText([_$createComponent(py.GeneratorDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Generators have a Yields section instead of a Returns section."
+        }), _$createComponent(py.PyDocExample, {
+          get children() {
+            return ["print([i for i in example_generator(4)])", _$createIntrinsic("br", {}), "[0, 1, 2, 3]"];
+          }
+        })];
+      },
+      parameters: [{
+        name: "n",
+        type: "int",
+        doc: "The upper limit of the range to generate, from 0 to n - 1."
+      }],
+      yields: "int: The next number in the range of 0 to n - 1.",
+      note: "Examples should be written in doctest format, and should illustrate how to use the function."
+    })]);
+    expect(res).toRenderTo(d`
+        """
+        Generators have a Yields section instead of a Returns section.
+
+        >> print([i for i in example_generator(4)])
+        >> [0, 1, 2, 3]
+
+        Args:
+            n (int): The upper limit of the range to generate, from 0 to n - 1.
+
+        Yields:
+            int: The next number in the range of 0 to n - 1.
+
+        Note:
+            Examples should be written in doctest format, and should illustrate how to use the function.
+        """
+
+
+        `);
   });
 });
 describe("Full example", () => {
@@ -289,17 +773,34 @@ describe("Full example", () => {
           }
         })];
       },
+      attributes: [{
+        name: "attr1",
+        type: "str",
+        children: "Description of attr1."
+      }, {
+        name: "attr2",
+        type: "int",
+        children: "Description of attr2."
+      }],
+      get examples() {
+        return [_$createComponent(py.PyDocExample, {
+          children: "print(\"class-doc\")"
+        })];
+      },
+      seeAlso: ["RelatedClass", "helper_function"],
+      warning: "This class is experimental.",
+      deprecated: "Use NewClass instead.",
       parameters: [{
         name: "somebody",
         type: "str",
-        optional: true,
         default: "John Doe",
-        doc: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., 'Agent X'). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller. Defaults to \"John Doe\"."
+        doc: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., 'Agent X'). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller."
       }, {
         name: "somebody2",
         type: "str",
         doc: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., 'Agent X'). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller."
       }],
+      note: "Do not include the 'self' parameter in the Args section.",
       style: "google"
     });
     const res = toSourceText([_$createComponent(py.ClassDeclaration, {
@@ -312,10 +813,10 @@ describe("Full example", () => {
               name: "just_name"
             }), _$createComponent(py.VariableDeclaration, {
               name: "name_and_type",
-              type: "number"
+              type: "int"
             }), _$createComponent(py.VariableDeclaration, {
               name: "name_type_and_value",
-              type: "number",
+              type: "int",
               initializer: 12
             })];
           }
@@ -337,6 +838,11 @@ describe("Full example", () => {
               >> x = "Hello"
               >> print(x)
 
+              Attributes:
+                  attr1 (str): Description of attr1.
+
+                  attr2 (int): Description of attr2.
+
               Args:
                   somebody (str, optional): Somebody's name. This can be any string
                       representing a person, whether it's a first name, full name,
@@ -350,10 +856,26 @@ describe("Full example", () => {
                       codename (e.g., 'Agent X'). It's used primarily for display
                       purposes, logging, or greeting messages and is not required to be
                       unique or validated unless specified by the caller.
+
+              Examples:
+                  >> print("class-doc")
+
+              See Also:
+                  RelatedClass
+                  helper_function
+
+              Warning:
+                  This class is experimental.
+
+              Deprecated:
+                  Use NewClass instead.
+
+              Note:
+                  Do not include the 'self' parameter in the Args section.
               """
               just_name = None
-              name_and_type: number = None
-              name_type_and_value: number = 12
+              name_and_type: int = None
+              name_type_and_value: int = 12
 
 
           `);
@@ -372,16 +894,17 @@ describe("Full example", () => {
       parameters: [{
         name: "somebody",
         type: "str",
-        optional: true,
         default: "John Doe",
-        doc: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., 'Agent X'). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller. Defaults to \"John Doe\"."
+        doc: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., 'Agent X'). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller."
       }, {
         name: "somebody2",
         type: "str",
         doc: "Somebody's name. This can be any string representing a person, whether it's a first name, full name, nickname, or even a codename (e.g., 'Agent X'). It's used primarily for display purposes, logging, or greeting messages and is not required to be unique or validated unless specified by the caller."
       }],
       returns: "The return value. True for success, False otherwise.",
+      yields: "int: The next number in the sequence.",
       raises: ["ValueError: If somebody2 is equal to somebody."],
+      note: "This function can be used as both a regular function and a generator.",
       style: "google"
     });
     const res = toSourceText([_$createComponent(py.FunctionDeclaration, {
@@ -436,8 +959,14 @@ describe("Full example", () => {
               Returns:
                   The return value. True for success, False otherwise.
 
+              Yields:
+                  int: The next number in the sequence.
+
               Raises:
                   ValueError: If somebody2 is equal to somebody.
+
+              Note:
+                  This function can be used as both a regular function and a generator.
               """
               just_name = None
               name_and_type: number = None
@@ -464,7 +993,14 @@ describe("Full example", () => {
             `);
   });
   it("classic enum with explicit values", () => {
-    const result = toSourceText([_$createComponent(py.EnumDeclaration, {
+    const doc = _$createComponent(py.ClassDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "An enum representing colors."
+        })];
+      }
+    });
+    const result = toSourceText([_$createComponent(py.ClassEnumDeclaration, {
       name: "Color",
       baseType: "IntEnum",
       members: [{
@@ -480,22 +1016,286 @@ describe("Full example", () => {
         value: "3",
         doc: "The color blue."
       }],
-      doc: "An enum representing colors."
+      doc: doc
     })], {
       externals: [enumModule]
     });
     const expected = d`
       from enum import IntEnum
 
-      # An enum representing colors.
       class Color(IntEnum):
-          RED = 1  # The color red.
-          GREEN = 2  # The color green.
-          BLUE = 3  # The color blue.
+          """
+          An enum representing colors.
+          """
+
+          RED = 1  #: The color red.
+          GREEN = 2  #: The color green.
+          BLUE = 3  #: The color blue.
 
 
     `;
     expect(result).toRenderTo(expected);
   });
+  it("ModuleDoc with SourceFile integration", () => {
+    const moduleDoc = _$createComponent(py.ModuleDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "This module provides utility functions for data processing. It includes functions for validation, transformation, and analysis."
+        })];
+      },
+      attributes: [{
+        name: "DEFAULT_TIMEOUT",
+        type: "int",
+        children: "Default timeout value in seconds."
+      }, {
+        name: "MAX_RETRIES",
+        type: "int",
+        children: "Maximum number of retry attempts."
+      }],
+      todo: ["Add caching functionality", "Improve error messages"],
+      style: "google"
+    });
+    const content = _$createComponent(py.SourceFile, {
+      path: "utils.py",
+      doc: moduleDoc,
+      get children() {
+        return [_$createComponent(py.VariableDeclaration, {
+          name: "DEFAULT_TIMEOUT",
+          initializer: 30
+        }), _$createComponent(py.VariableDeclaration, {
+          name: "MAX_RETRIES",
+          initializer: 3
+        }), _$createComponent(py.FunctionDeclaration, {
+          name: "process_data",
+          children: "pass"
+        })];
+      }
+    });
+    const res = toSourceTextMultiple([content]);
+    const file = res.contents.find(f => f.kind === "file" && f.path === "utils.py");
+    expect(file).toBeDefined();
+    assertFileContents(res, {
+      "utils.py": d`
+        """
+        This module provides utility functions for data processing. It includes
+        functions for validation, transformation, and analysis.
+
+        Attributes:
+            DEFAULT_TIMEOUT (int): Default timeout value in seconds.
+
+            MAX_RETRIES (int): Maximum number of retry attempts.
+
+        Todo:
+            * Add caching functionality
+            * Improve error messages
+        """
+
+
+        default_timeout = 30
+
+        max_retries = 3
+
+        def process_data():
+            pass
+
+
+        `
+    });
+  });
+  it("GeneratorDoc with FunctionDeclaration integration", () => {
+    const generatorDoc = _$createComponent(py.GeneratorDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "A generator function that yields fibonacci numbers. This is an efficient way to generate the sequence on demand."
+        })];
+      },
+      parameters: [{
+        name: "n",
+        type: "int",
+        doc: "Number of fibonacci numbers to generate."
+      }],
+      yields: "int: The next fibonacci number in the sequence.",
+      style: "google"
+    });
+    const result = toSourceText([_$createComponent(py.FunctionDeclaration, {
+      name: "fibonacci_generator",
+      doc: generatorDoc,
+      children: "yield 0"
+    })]);
+    expect(result).toRenderTo(d`
+        def fibonacci_generator():
+            """
+            A generator function that yields fibonacci numbers. This is an efficient way
+            to generate the sequence on demand.
+
+            Args:
+                n (int): Number of fibonacci numbers to generate.
+
+            Yields:
+                int: The next fibonacci number in the sequence.
+            """
+            yield 0
+
+
+        `);
+  });
+  it("ExceptionDoc with ClassDeclaration integration", () => {
+    const exceptionDoc = _$createComponent(py.ExceptionDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Custom exception raised when data validation fails. This exception includes details about the validation error."
+        })];
+      },
+      attributes: [{
+        name: "field_name",
+        type: "str",
+        children: "Name of the field that failed validation."
+      }, {
+        name: "error_code",
+        type: "int",
+        children: "Numeric error code for the validation failure."
+      }],
+      style: "google"
+    });
+    const result = toSourceText([_$createComponent(py.ClassDeclaration, {
+      name: "ValidationError",
+      bases: ["Exception"],
+      doc: exceptionDoc,
+      get children() {
+        return _$createComponent(py.StatementList, {
+          get children() {
+            return [_$createComponent(py.VariableDeclaration, {
+              name: "field_name",
+              type: "str"
+            }), _$createComponent(py.VariableDeclaration, {
+              name: "error_code",
+              type: "int"
+            })];
+          }
+        });
+      }
+    })]);
+    expect(result).toRenderTo(d`
+        class ValidationError(Exception):
+            """
+            Custom exception raised when data validation fails. This exception includes
+            details about the validation error.
+
+            Attributes:
+                field_name (str): Name of the field that failed validation.
+
+                error_code (int): Numeric error code for the validation failure.
+            """
+            field_name: str = None
+            error_code: int = None
+
+
+        `);
+  });
+  it("PropertyDoc with FunctionDeclaration (as property method) integration", () => {
+    const propertyDoc = _$createComponent(py.PropertyDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "The full name of the person, combining first and last name. This property automatically formats the name with proper capitalization."
+        })];
+      },
+      style: "google"
+    });
+    const result = toSourceText([_$createComponent(py.ClassDeclaration, {
+      name: "Person",
+      get children() {
+        return _$createComponent(py.PropertyDeclaration, {
+          name: "full_name",
+          doc: propertyDoc,
+          type: "str",
+          children: "return \"John Doe\""
+        });
+      }
+    })]);
+    expect(result).toRenderTo(d`
+        class Person:
+            @property
+            def full_name(self) -> str:
+                """
+                The full name of the person, combining first and last name. This
+                property automatically formats the name with proper capitalization.
+                """
+                return "John Doe"
+
+
+
+
+
+        `);
+  });
+  it("MethodDoc with FunctionDeclaration (inside class) integration", () => {
+    const methodDoc = _$createComponent(py.MethodDoc, {
+      get description() {
+        return [_$createComponent(Prose, {
+          children: "Validates the input data according to the defined schema. This method performs comprehensive validation including type checking."
+        })];
+      },
+      parameters: [{
+        name: "data",
+        type: "dict",
+        doc: "The data dictionary to validate."
+      }, {
+        name: "strict",
+        type: "bool",
+        default: "True",
+        doc: "Whether to enforce strict validation rules."
+      }],
+      returns: "bool: True if validation passes, False otherwise.",
+      raises: ["ValidationError: If data format is invalid."],
+      note: "This method modifies the internal validation state.",
+      style: "google"
+    });
+    const result = toSourceText([_$createComponent(py.ClassDeclaration, {
+      name: "DataValidator",
+      get children() {
+        return _$createComponent(py.MethodDeclaration, {
+          name: "validate",
+          doc: methodDoc,
+          parameters: [{
+            name: "data",
+            type: "dict"
+          }, {
+            name: "strict",
+            type: "bool",
+            default: true
+          }],
+          returnType: "bool",
+          children: "return self.validate(data, strict)"
+        });
+      }
+    })]);
+    expect(result).toRenderTo(d`
+        class DataValidator:
+            def validate(self, data: dict, strict: bool = True) -> bool:
+                """
+                Validates the input data according to the defined schema. This method
+                performs comprehensive validation including type checking.
+
+                Args:
+                    data (dict): The data dictionary to validate.
+
+                    strict (bool, optional): Whether to enforce strict validation rules.
+                        Defaults to "True".
+
+                Returns:
+                    bool: True if validation passes, False otherwise.
+
+                Raises:
+                    ValidationError: If data format is invalid.
+
+                Note:
+                    This method modifies the internal validation state.
+                """
+                return self.validate(data, strict)
+
+
+
+        `);
+  });
 });
 //# sourceMappingURL=pydocs.test.js.map