Generated docs for missing docstrings (#241)

# Motivation
Many attributes are missing docstrings

# Content
<!-- Please include a summary of the change -->
# Testing
<!-- How was the change tested? -->
# Please check the following before marking your PR as ready for review

- [x] I have added tests for my changes
- [x] I have updated the documentation or added new documentation as
needed

Author: jemeza-codegen

src/codegen/git/models/pr_options.py

@@ -5,7 +5,14 @@
 
 @apidoc
 class PROptions(BaseModel):
-    """Options for generating a PR."""
+    """Options for generating a PR.
+
+    Attributes:
+        title: The title of the pull request.
+        body: The body content of the pull request.
+        labels: A list of labels to be added to the pull request.
+        force_push_head_branch: Whether to force push the head branch.
+    """
 
     title: str | None = None
     body: str | None = None

src/codegen/sdk/code_generation/doc_utils/generate_docs_json.py

@@ -9,10 +9,25 @@
 from codegen.sdk.core.codebase import Codebase
 from codegen.sdk.core.placeholder.placeholder_type import TypePlaceholder
 
-ATTRIBUTES_TO_IGNORE = ["G", "node_id", "angular"]
-
-
-def generate_docs_json(codebase: Codebase, head_commit: str) -> dict[str, dict[str, Any]]:
+ATTRIBUTES_TO_IGNORE = [
+    "G",
+    "node_id",
+    "angular",
+    "model_config",
+    "constructor_keyword",
+    "viz",
+    "console",
+    "items",
+    "node_type",
+    "ts_node",
+    "file_node_id",
+    "G",
+    "statement_type",
+    "assignment_types",
+]
+
+
+def generate_docs_json(codebase: Codebase, head_commit: str, raise_on_missing_docstring: bool = False) -> dict[str, dict[str, Any]]:
     """Update documentation table for classes, methods and attributes in the codebase.
 
     Args:
@@ -23,7 +38,6 @@ def generate_docs_json(codebase: Codebase, head_commit: str) -> dict[str, dict[s
     """
     codegen_sdk_docs = GSDocs(classes=[])
     types_cache = {}
-    attr_cache = {}
 
     def process_class_doc(cls):
         """Update or create documentation for a class."""
@@ -110,22 +124,22 @@ def process_attribute(attr, cls, cls_doc, seen_methods):
             return
 
         attr_path = create_path(attr, cls)
-        original_attr_path = create_path(attr)
 
-        if original_attr_path not in attr_cache:
-            description = attr.docstring(cls)
-            attr_return_type = []
-            if r_type := get_type_str(attr):
-                if isinstance(r_type, TypePlaceholder):
-                    resolved_types = []
-                else:
-                    resolved_types = r_type.resolved_types
-                r_type_source = replace_multiple_types(codebase=codebase, input_str=r_type.source, resolved_types=resolved_types, parent_class=cls, parent_symbol=attr, types_cache=types_cache)
-                attr_return_type.append(r_type_source)
+        description = attr.docstring(attr.parent_class)
+        if raise_on_missing_docstring and not description:
+            msg = f"Attribute {attr.parent_class.name}.{attr.name} does not have a docstring"
+            raise ValueError(msg)
+        attr_return_type = []
+        if r_type := get_type_str(attr):
+            if isinstance(r_type, TypePlaceholder):
+                resolved_types = []
+            else:
+                resolved_types = r_type.resolved_types
+            r_type_source = replace_multiple_types(codebase=codebase, input_str=r_type.source, resolved_types=resolved_types, parent_class=cls, parent_symbol=attr, types_cache=types_cache)
+            attr_return_type.append(r_type_source)
 
-            attr_cache[original_attr_path] = {"description": description, "attr_return_type": attr_return_type}
+        attr_info = {"description": description, "attr_return_type": attr_return_type}
 
-        attr_info = attr_cache[original_attr_path]
         meta_data = {"parent": create_path(attr.parent_class), "path": attr.file.filepath}
 
         return MethodDoc(

src/codegen/sdk/codebase/span.py

@@ -54,7 +54,12 @@ def range_json_schema() -> JsonSchemaValue:
 
 @apidoc
 class Span(BaseModel):
-    """Range within the codebase"""
+    """Range within the codebase
+
+    Attributes:
+        range: Adapter for the range within the codebase.
+        filepath: The path to the file associated with the range.
+    """
 
     model_config = ConfigDict(
         frozen=True,

src/codegen/sdk/core/assignment.py

@@ -45,15 +45,14 @@
 class Assignment(Symbol[Parent, ...], Typeable[Parent, ...], HasValue, Generic[Parent]):
     """Represents an assignment for a single variable within an assignment statement.
 
-    Attributes:
-        left: The left side of the assignment
-        right: The right side of the assignment
-
     Example:
         ```typescript
         var z
         var z = 5
         ```
+
+    Attributes:
+        symbol_type: The type of symbol, set to SymbolType.GlobalVar.
     """
 
     _left: Expression[Self]

src/codegen/sdk/core/class_definition.py

@@ -51,7 +51,13 @@
 
 @apidoc
 class Class(Inherits[TType], HasBlock[TCodeBlock, TDecorator], Callable[TParameter, TType], HasAttribute[TFunction | Attribute], Generic[TFunction, TDecorator, TCodeBlock, TParameter, TType]):
-    """Abstract representation of a Class definition."""
+    """Abstract representation of a Class definition.
+
+    Attributes:
+        symbol_type: The type of symbol, set to SymbolType.Class.
+        constructor_keyword: The keyword used to identify the constructor method.
+        parent_classes: The parent classes of this class, if any.
+    """
 
     symbol_type = SymbolType.Class
     constructor_keyword = None

src/codegen/sdk/core/codebase.py

@@ -106,7 +106,10 @@
 class Codebase(Generic[TSourceFile, TDirectory, TSymbol, TClass, TFunction, TImport, TGlobalVar, TInterface, TTypeAlias, TParameter, TCodeBlock]):
     """This class provides the main entrypoint for most programs to analyzing and manipulating codebases.
 
-    It provides a high-level interface to interact with the codebase graph, and provides methods to access and manipulate files, directories, symbols, and other entities in the codebase.
+    Attributes:
+        viz: Manages visualization of the codebase graph.
+        repo_path: The path to the repository.
+        console: Manages console output for the codebase.
     """
 
     _op: RepoOperator | RemoteRepoOperator

src/codegen/sdk/core/dataclasses/usage.py

@@ -27,6 +27,7 @@ class Usage:
     Attributes:
         match: The exact match of the usage
         usage_symbol: The symbol this object is used in
+        imported_by: The import statement that brought this symbol into scope, or None if not imported
         usage_type: How this symbol was used
         kind: Where this symbol was used (IE: in a type parameter or in the body of the class, etc)
     """
@@ -62,15 +63,17 @@ class UsageKind(IntEnum):
 
     Attributes:
         SUBCLASS: Used in symbol inheritance.
-        TYPE_ANNOTATION:  Used as a type annotation on a parameter or assignment statement.
+        TYPED_PARAMETER: Used as a typed parameter in a function/method.
+        TYPE_ANNOTATION: Used as a type annotation on a parameter or assignment statement.
         BODY: Usage within the body of a function/method.
         DECORATOR: Usage within a decorator.
-        RETURN_TYPE: Used as a return type annotation
+        RETURN_TYPE: Used as a return type annotation.
         TYPE_DEFINITION: Used in a type alias.
         EXPORTED_SYMBOL: Used in an export statement.
         EXPORTED_WILDCARD: Re-exported by a wildcard export.
         GENERIC: Used as a type parameter to another type.
         IMPORTED: Imported with an import statement.
+        IMPORTED_WILDCARD: Imported with a wildcard import statement.
         DEFAULT_VALUE: Represents a default value in a function/method parameter.
     """
 

src/codegen/sdk/core/detached_symbols/code_block.py

@@ -45,6 +45,10 @@ class CodeBlock(Expression[Parent], Generic[Parent, TAssignment]):
     function body or class body.
 
     Enables various types of queries and operations on the code block.
+
+    Attributes:
+        level: The indentation level of the code block.
+        parent_block: The parent code block containing this block, or None if it is a top-level block.
     """
 
     level: int

src/codegen/sdk/core/directory.py

@@ -39,7 +39,14 @@
 @apidoc
 class Directory(Generic[TFile, TSymbol, TImportStatement, TGlobalVar, TClass, TFunction, TImport]):
     """Directory representation for codebase.
+
     GraphSitter abstraction of a file directory that can be used to look for files and symbols within a specific directory.
+
+    Attributes:
+        path: Absolute path of the directory.
+        dirpath: Relative path of the directory.
+        parent: The parent directory, if any.
+        items: A dictionary containing files and subdirectories within the directory.
     """
 
     path: Path  # Absolute Path

src/codegen/sdk/core/export.py

@@ -21,7 +21,11 @@
 
 @apidoc
 class Export(Exportable[Parent], Generic[Parent]):
-    """Represents a single symbol being exported."""
+    """Represents a single symbol being exported.
+
+    Attributes:
+        export_statement: The statement representing the export.
+    """
 
     export_statement: ExportStatement
 

src/codegen/sdk/core/expressions/binary_expression.py

@@ -23,7 +23,12 @@
 
 @apidoc
 class BinaryExpression(Expression[Parent], Chainable, Generic[Parent]):
-    """Represents binary expressions, e.g. all of +,-,*,/, as well as booleaneoperations (and, or) etc."""
+    """Represents binary expressions, e.g. all of +,-,*,/, as well as boolean operations (and, or) etc.
+
+    Attributes:
+        left: The left operand of the binary expression.
+        right: The right operand of the binary expression.
+    """
 
     left: Expression[Self] | None
     right: Expression[Self] | None

src/codegen/sdk/core/expressions/expression.py

@@ -13,7 +13,11 @@
 
 @apidoc
 class Expression(Editable[Parent], Generic[Parent]):
-    """Represents an arbitrary Expression, such as List, Dict, Binary Expression, String."""
+    """Represents an arbitrary Expression, such as List, Dict, Binary Expression, String.
+
+    Attributes:
+        node_type: The type of the node, set to NodeType.EXPRESSION.
+    """
 
     node_type: NodeType = NodeType.EXPRESSION
 

src/codegen/sdk/core/expressions/multi_expression.py

@@ -21,7 +21,11 @@
 
 @apidoc
 class MultiExpression(Expression[Parent], Generic[Parent, TExpression]):
-    """Represents an group of Expressions, such as List, Dict, Binary Expression, String."""
+    """Represents an group of Expressions, such as List, Dict, Binary Expression, String.
+
+    Attributes:
+        expressions: A list of expressions contained within the MultiExpression.
+    """
 
     expressions: list[TExpression]
 

src/codegen/sdk/core/expressions/string.py

@@ -26,7 +26,8 @@ class String(Expression[Parent], Builtin, Generic[Parent]):
 
     Attributes:
         content: The content of the string
-        expressions: embedded expressions in the string, only applicable for templated or formatted strings
+        content_nodes: A collection of string fragments and escape sequences in TS, or a single string content in Python.
+        expressions: Embedded expressions in the string, only applicable for templated or formatted strings.
     """
 
     content: str

src/codegen/sdk/core/expressions/subscript_expression.py

@@ -26,6 +26,11 @@ class SubscriptExpression(Expression[Parent], Resolvable[Parent], Generic[Object
 
     Examples:
      A[]
+
+    Attributes:
+        object: The object being indexed.
+        indices: A list of indices used for indexing the object.
+
     """
 
     object: Object

src/codegen/sdk/core/expressions/ternary_expression.py

@@ -19,7 +19,13 @@
 
 @apidoc
 class TernaryExpression(Expression[Parent], Chainable, Generic[Parent]):
-    """Any ternary expression in the code where a condition will determine branched execution."""
+    """Any ternary expression in the code where a condition will determine branched execution.
+
+    Attributes:
+        condition: The condition expression that determines which branch to execute.
+        consequence: The expression to execute if the condition is true.
+        alternative: The expression to execute if the condition is false.
+    """
 
     condition: Expression[Self] | None
     consequence: Expression[Self] | None

src/codegen/sdk/core/external_module.py

@@ -29,9 +29,11 @@ class ExternalModule(
 ):
     """Represents an external module, like `datetime`, that can be referenced.
 
-    These are only added to the graph during import resolution and will not exist in a local file's
-    subgraph. This is because we don't know what an import is referencing or resolves to until we
-    see the full codebase.
+    These are only added to the graph during import resolution and will not exist in a local file's subgraph. This is because we don't know what an import is referencing or resolves to until we see
+    the full codebase.
+
+    Attributes:
+        node_type: The type of node, set to NodeType.EXTERNAL.
     """
 
     node_type: Literal[NodeType.EXTERNAL] = NodeType.EXTERNAL

src/codegen/sdk/core/file.py

@@ -54,6 +54,12 @@ class File(Editable[None]):
     """Represents a generic file.
 
     Could represent a source file or a non-code file such as a markdown file or image file.
+
+    Attributes:
+        name: The name of the file.
+        file_path: The relative file path as a string.
+        path: The absolute path of the file as a Path object.
+        node_type: The type of node, set to NodeType.FILE.
     """
 
     name: str
@@ -432,6 +438,9 @@ class SourceFile(
 
     Enables creating, reading, updating, and deleting files and searching through their contents,
     etc.
+
+    Attributes:
+        code_block: Represents the block of code contained in the file.
     """
 
     code_block: TCodeBlock

src/codegen/sdk/core/function.py

@@ -50,7 +50,7 @@ class Function(
     """Abstract representation of a Function.
 
     Attributes:
-        return_type: the return type annotation of the function
+        symbol_type: The type of symbol, set to SymbolType.Function.
     """
 
     symbol_type = SymbolType.Function

src/codegen/sdk/core/import_resolution.py

@@ -61,17 +61,14 @@ class ImportResolution(Generic[TSourceFile]):
 class Import(Usable[ImportStatement], Chainable, Generic[TSourceFile], HasAttribute[TSourceFile]):
     """Represents a single symbol being imported.
 
-    For example, this is one `Import` in Python (and similar applies to Typescript, etc.):
-    ```
-    from a.b import c
-    ```
-
-    This is two separate `Import` in Python:
-    ```
-    from a.b import c, d  # one import for each `c` and `d`
-    ```
     Attributes:
+        to_file_id: The node ID of the file to which this import belongs.
+        module: The module from which the symbol is being imported, if applicable.
         symbol_name: The name of the symbol being imported. For instance import a as b has a symbol_name of a.
+        alias: The alias of the imported symbol, if one exists.
+        node_type: The type of node, set to NodeType.IMPORT.
+        import_type: The type of import, indicating how the symbol is imported.
+        import_statement: The statement that this import is part of.
         import_statement: the ImportStatement that this import belongs to
     """
 

src/codegen/sdk/core/interfaces/callable.py

@@ -43,6 +43,9 @@ class Callable(Usable, Generic[TParameter, TType]):
     """Any symbol that can be invoked with arguments eg.
 
     Function, Class, Decorator, ExternalModule
+
+    Attributes:
+        return_type: The type of value returned by the callable, or a placeholder.
     """
 
     _parameters: SymbolGroup[TParameter, Self] | list[TParameter]

src/codegen/sdk/core/interfaces/editable.py

@@ -99,8 +99,12 @@ def _is_empty_container(text: str) -> bool:
 class Editable(JSONable, Generic[Parent]):
     """An editable instance is an abstract text representation of any text in a file.
 
-    The editable APIs enables text search and edit within the given Editable wrapper around any
-    group of text in a file.
+    Attributes:
+        ts_node: The TreeSitter node associated with this Editable instance.
+        file_node_id: The unique identifier for the file node.
+        G: The codebase graph that this Editable instance is part of.
+        parent: The parent node of this Editable instance.
+        node_type: The type of node this Editable instance represents.
     """
 
     ts_node: TSNode