@alloy-js/python 0.2.0-dev.2 → 0.2.0-dev.4

package/test/pydocs.test.tsx

@@ -3,7 +3,11 @@ 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.jsx";
+import {
+  assertFileContents,
+  toSourceText,
+  toSourceTextMultiple,
+} from "./utils.jsx";
 
 describe("PyDoc", () => {
   it("formats properly", () => {
@@ -128,172 +132,788 @@ describe("PyDocExample", () => {
   });
 });
 
-describe("GoogleStyleDocParam", () => {
-  it("name only", () => {
+describe("SimpleCommentBlock", () => {
+  it("renders simple comment block", () => {
     const res = toSourceText([
-      <py.PyDoc>
-        <py.GoogleStyleDocParam name="somebody" />
-      </py.PyDoc>,
+      <py.SimpleCommentBlock>
+        This is a simple comment block that spans multiple lines.
+      </py.SimpleCommentBlock>,
     ]);
     expect(res).toRenderTo(
       d`
-          """
-          somebody
-          """
+          # This is a simple comment block that spans multiple lines.
+          
+          `,
+    );
+  });
 
+  it("renders comment block with line breaks", () => {
+    const res = toSourceText([
+      <py.SimpleCommentBlock>
+        First line of comment.
+        <br />
+        Second line of comment.
+      </py.SimpleCommentBlock>,
+    ]);
+    expect(res).toRenderTo(
+      d`
+          # First line of comment. Second line of comment.
+          
+          `,
+    );
+  });
+});
 
+describe("SimpleInlineComment", () => {
+  it("renders inline comment", () => {
+    const res = toSourceText([
+      <>
+        x = 42
+        <py.SimpleInlineComment>
+          This is an inline comment
+        </py.SimpleInlineComment>
+      </>,
+    ]);
+    expect(res).toRenderTo(
+      d`
+          x = 42  # This is an inline comment
           `,
     );
   });
-  it("name and type", () => {
+
+  it("renders inline comment with complex text", () => {
     const res = toSourceText([
-      <py.PyDoc>
-        <py.GoogleStyleDocParam name="somebody" type="str" />
-      </py.PyDoc>,
+      <>
+        result = calculate()
+        <py.SimpleInlineComment>
+          TODO: Add error handling here
+        </py.SimpleInlineComment>
+      </>,
+    ]);
+    expect(res).toRenderTo(
+      d`
+          result = calculate()  # TODO: Add error handling here
+          `,
+    );
+  });
+});
+
+describe("SimpleInlineMemberComment", () => {
+  it("renders inline member comment", () => {
+    const res = toSourceText([
+      <>
+        status: int
+        <py.SimpleInlineMemberComment>
+          HTTP status code
+        </py.SimpleInlineMemberComment>
+      </>,
+    ]);
+    expect(res).toRenderTo(
+      d`
+          status: int  #: HTTP status code
+          `,
+    );
+  });
+
+  it("renders inline member comment for variable declaration", () => {
+    const res = toSourceText([
+      <>
+        max_retries = 3
+        <py.SimpleInlineMemberComment>
+          Maximum number of retry attempts
+        </py.SimpleInlineMemberComment>
+      </>,
+    ]);
+    expect(res).toRenderTo(
+      d`
+          max_retries = 3  #: Maximum number of retry attempts
+          `,
+    );
+  });
+});
+
+describe("New Documentation Components", () => {
+  it("ModuleDoc renders correctly", () => {
+    const res = toSourceText([
+      <py.ModuleDoc
+        description={[
+          <Prose>
+            This module demonstrates documentation as specified by the Google
+            Python Style Guide.
+          </Prose>,
+        ]}
+        attributes={[
+          {
+            name: "module_level_variable1",
+            type: "int",
+            children: "Module level variables may be documented.",
+          },
+        ]}
+        examples={[<py.PyDocExample>print("mod")</py.PyDocExample>]}
+        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("PropertyDoc renders correctly", () => {
+    const res = toSourceText([
+      <py.PropertyDoc
+        description={[
+          <Prose>
+            Properties should be documented in their getter method.
+          </Prose>,
+        ]}
+        returns="str: The readonly property value."
+        examples={[<py.PyDocExample>print(obj.name)</py.PyDocExample>]}
+        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`
+        """
+        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("GeneratorDoc renders correctly", () => {
+    const res = toSourceText([
+      <py.GeneratorDoc
+        description={[
+          <Prose>
+            Generators have a Yields section instead of a Returns section.
+          </Prose>,
+        ]}
+        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."
+        examples={[<py.PyDocExample>print(next(gen))</py.PyDocExample>]}
+        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`
+        """
+        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("ExceptionDoc renders correctly", () => {
+    const res = toSourceText([
+      <py.ExceptionDoc
+        description={[
+          <Prose>Exceptions are documented in the same way as classes.</Prose>,
+        ]}
+        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`
+        """
+        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("MethodDoc renders correctly without default note", () => {
+    const res = toSourceText([
+      <py.MethodDoc
+        description={[
+          <Prose>Class methods are similar to regular functions.</Prose>,
+        ]}
+        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`
+        """
+        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("MethodDoc renders correctly with custom note", () => {
+    const res = toSourceText([
+      <py.MethodDoc
+        description={[
+          <Prose>Class methods are similar to regular functions.</Prose>,
+        ]}
+        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([
+      <py.ModuleDoc
+        description={[<Prose>Simple module description.</Prose>]}
+      />,
+    ]);
+
+    expect(res).toRenderTo(
+      d`
+        """
+        Simple module description.
+        """
+
+
+        `,
+    );
+  });
+
+  it("ModuleDoc with only todo items", () => {
+    const res = toSourceText([
+      <py.ModuleDoc
+        description={[<Prose>Module with pending tasks.</Prose>]}
+        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([
+      <py.PropertyDoc
+        description={[<Prose>A simple readonly property.</Prose>]}
+      />,
+    ]);
+
+    expect(res).toRenderTo(
+      d`
+        """
+        A simple readonly property.
+        """
+
+
+        `,
+    );
+  });
+
+  it("PropertyDoc with getter and setter info", () => {
+    const res = toSourceText([
+      <py.PropertyDoc
+        description={[
+          <Prose>
+            Properties with both a getter and setter should only be documented
+            in their getter method.
+          </Prose>,
+        ]}
+        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([
+      <py.GeneratorDoc
+        description={[
+          <Prose>
+            A more complex generator example with multiple parameters.
+          </Prose>,
+        ]}
+        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([
+      <py.ExceptionDoc
+        description={[
+          <Prose>A custom exception for authentication failures.</Prose>,
+          <Prose>
+            This exception is raised when authentication credentials are invalid
+            or when authentication tokens have expired.
+          </Prose>,
+        ]}
+        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`
-          """
-          somebody (str)
-          """
+        """
+        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("name, type and description", () => {
+
+  it("MethodDoc with raises but no returns", () => {
     const res = toSourceText([
-      <py.PyDoc>
-        <py.GoogleStyleDocParam name="somebody" type="str">
-          Somebody's name.
-        </py.GoogleStyleDocParam>
-      </py.PyDoc>,
+      <py.MethodDoc
+        description={[
+          <Prose>
+            A method that performs an action but doesn't return a value.
+          </Prose>,
+        ]}
+        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`
-          """
-          somebody (str): Somebody's name.
-          """
+        """
+        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("name, type, description, and optional", () => {
+
+  it("MethodDoc with no parameters", () => {
     const res = toSourceText([
-      <py.PyDoc>
-        <py.GoogleStyleDocParam name="somebody" type="str" optional>
-          Somebody's name.
-        </py.GoogleStyleDocParam>
-      </py.PyDoc>,
+      <py.MethodDoc
+        description={[
+          <Prose>A simple method with no parameters (except self).</Prose>,
+        ]}
+        returns="bool: True if the operation was successful."
+        note="This is a parameterless method that only operates on instance state."
+      />,
     ]);
+
     expect(res).toRenderTo(
       d`
-          """
-          somebody (str, optional): Somebody's name.
-          """
+        """
+        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", () => {
+
+  it("AttributeDoc standalone usage", () => {
     const res = toSourceText([
       <py.PyDoc>
-        <py.GoogleStyleDocParam
-          name="somebody"
-          type="str"
-          optional
-          defaultValue="John Doe"
-        >
-          Somebody's name.
-        </py.GoogleStyleDocParam>
+        <py.AttributeDoc name="connection_timeout" type="float">
+          Maximum time in seconds to wait for a connection to be established.
+        </py.AttributeDoc>
       </py.PyDoc>,
     ]);
+
     expect(res).toRenderTo(
       d`
         """
-        somebody (str, optional): Somebody's name. Defaults to \"John Doe\".
+        connection_timeout (float): Maximum time in seconds to wait for a connection to
+            be established.
         """
 
 
         `,
     );
   });
-  it("name, type, description, and optional with default value with a very long description", () => {
-    const res = toSourceText(
-      [
-        <py.PyDoc>
-          <py.GoogleStyleDocParam
-            name="somebody"
-            type="str"
-            optional
-            defaultValue="John Doe"
-          >
-            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.
-          </py.GoogleStyleDocParam>
-          <py.GoogleStyleDocParam name="somebody2" type="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.
-          </py.GoogleStyleDocParam>
-        </py.PyDoc>,
-      ],
-      { printOptions: { printWidth: 80 } },
-    );
-    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.
-          """
 
+  it("GeneratorDoc with examples in description", () => {
+    const res = toSourceText([
+      <py.GeneratorDoc
+        description={[
+          <Prose>
+            Generators have a Yields section instead of a Returns section.
+          </Prose>,
+          <py.PyDocExample>
+            print([i for i in example_generator(4)])
+            <br />
+            [0, 1, 2, 3]
+          </py.PyDocExample>,
+        ]}
+        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."
+      />,
+    ]);
 
-          `,
-    );
-  });
-  it("name, type, description, and optional with default value with a description containing a linebreak", () => {
-    const res = toSourceText(
-      [
-        <py.PyDoc>
-          <py.GoogleStyleDocParam
-            name="somebody"
-            type="str"
-            optional
-            defaultValue="John Doe"
-          >
-            Somebody's name. This is one line
-            <hbr />
-            This is another line.
-          </py.GoogleStyleDocParam>
-        </py.PyDoc>,
-      ],
-      { 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\".
-          """
+        """
+        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.
+        """
+
+
+        `,
     );
   });
 });
@@ -315,13 +935,28 @@ describe("Full example", () => {
             print(x)
           </py.PyDocExample>,
         ]}
+        attributes={[
+          {
+            name: "attr1",
+            type: "str",
+            children: "Description of attr1.",
+          },
+          {
+            name: "attr2",
+            type: "int",
+            children: "Description of attr2.",
+          },
+        ]}
+        examples={[<py.PyDocExample>print("class-doc")</py.PyDocExample>]}
+        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",
@@ -329,6 +964,7 @@ describe("Full example", () => {
             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"
       />
     );
@@ -337,10 +973,10 @@ describe("Full example", () => {
         <py.ClassDeclaration name="A" doc={doc}>
           <py.StatementList>
             <py.VariableDeclaration name="just_name" />
-            <py.VariableDeclaration name="name_and_type" type="number" />
+            <py.VariableDeclaration name="name_and_type" type="int" />
             <py.VariableDeclaration
               name="name_type_and_value"
-              type="number"
+              type="int"
               initializer={12}
             />
           </py.StatementList>
@@ -360,6 +996,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,
@@ -373,10 +1014,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
 
 
           `,
@@ -403,9 +1060,8 @@ describe("Full example", () => {
           {
             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",
@@ -414,7 +1070,9 @@ 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."
         style="google"
       />
     );
@@ -463,8 +1121,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
@@ -497,9 +1161,14 @@ describe("Full example", () => {
   });
 
   it("classic enum with explicit values", () => {
+    const doc = (
+      <py.ClassDoc
+        description={[<Prose>An enum representing colors.</Prose>]}
+      />
+    );
     const result = toSourceText(
       [
-        <py.EnumDeclaration
+        <py.ClassEnumDeclaration
           name="Color"
           baseType="IntEnum"
           members={[
@@ -507,7 +1176,7 @@ describe("Full example", () => {
             { name: "GREEN", value: "2", doc: "The color green." },
             { name: "BLUE", value: "3", doc: "The color blue." },
           ]}
-          doc="An enum representing colors."
+          doc={doc}
         />,
       ],
       { externals: [enumModule] },
@@ -515,14 +1184,309 @@ describe("Full example", () => {
     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 = (
+      <py.ModuleDoc
+        description={[
+          <Prose>
+            This module provides utility functions for data processing. It
+            includes functions for validation, transformation, and analysis.
+          </Prose>,
+        ]}
+        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 = (
+      <py.SourceFile path="utils.py" doc={moduleDoc}>
+        <py.VariableDeclaration name="DEFAULT_TIMEOUT" initializer={30} />
+        <py.VariableDeclaration name="MAX_RETRIES" initializer={3} />
+        <py.FunctionDeclaration name="process_data">
+          pass
+        </py.FunctionDeclaration>
+      </py.SourceFile>
+    );
+
+    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 = (
+      <py.GeneratorDoc
+        description={[
+          <Prose>
+            A generator function that yields fibonacci numbers. This is an
+            efficient way to generate the sequence on demand.
+          </Prose>,
+        ]}
+        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([
+      <py.FunctionDeclaration name="fibonacci_generator" doc={generatorDoc}>
+        yield 0
+      </py.FunctionDeclaration>,
+    ]);
+
+    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 = (
+      <py.ExceptionDoc
+        description={[
+          <Prose>
+            Custom exception raised when data validation fails. This exception
+            includes details about the validation error.
+          </Prose>,
+        ]}
+        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([
+      <py.ClassDeclaration
+        name="ValidationError"
+        bases={["Exception"]}
+        doc={exceptionDoc}
+      >
+        <py.StatementList>
+          <py.VariableDeclaration name="field_name" type="str" />
+          <py.VariableDeclaration name="error_code" type="int" />
+        </py.StatementList>
+      </py.ClassDeclaration>,
+    ]);
+
+    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 = (
+      <py.PropertyDoc
+        description={[
+          <Prose>
+            The full name of the person, combining first and last name. This
+            property automatically formats the name with proper capitalization.
+          </Prose>,
+        ]}
+        style="google"
+      />
+    );
+
+    const result = toSourceText([
+      <py.ClassDeclaration name="Person">
+        <py.PropertyDeclaration name="full_name" doc={propertyDoc} type="str">
+          return "John Doe"
+        </py.PropertyDeclaration>
+      </py.ClassDeclaration>,
+    ]);
+
+    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 = (
+      <py.MethodDoc
+        description={[
+          <Prose>
+            Validates the input data according to the defined schema. This
+            method performs comprehensive validation including type checking.
+          </Prose>,
+        ]}
+        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([
+      <py.ClassDeclaration name="DataValidator">
+        <py.MethodDeclaration
+          name="validate"
+          doc={methodDoc}
+          parameters={[
+            { name: "data", type: "dict" },
+            { name: "strict", type: "bool", default: true },
+          ]}
+          returnType="bool"
+        >
+          return self.validate(data, strict)
+        </py.MethodDeclaration>
+      </py.ClassDeclaration>,
+    ]);
+
+    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)
+
+
+
+        `,
+    );
+  });
 });