CG-10472: Adds docstrings to class attributes missing docstrings

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: A flag indicating 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

@@ -12,7 +12,7 @@
 ATTRIBUTES_TO_IGNORE = ["G", "node_id", "angular"]
 
 
-def generate_docs_json(codebase: Codebase, head_commit: str) -> dict[str, dict[str, Any]]:
+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:
@@ -110,22 +110,22 @@
             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,13 @@ def range_json_schema() -> JsonSchemaValue:
 
 @apidoc
 class Span(BaseModel):
-    """Range within the codebase"""
+    """Range within the codebase
+
+    Attributes:
+        model_config: Configuration for the model, including JSON encoders.
+        range: Adapter for the range within the codebase.
+        filepath: Path to the file associated with the range.
+    """
 
     model_config = ConfigDict(
         frozen=True,

src/codegen/sdk/core/assignment.py

@@ -46,14 +46,8 @@ class Assignment(Symbol[Parent, ...], Typeable[Parent, ...], HasValue, Generic[P
     """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
-        ```
+        _left: The internal representation of the left side of the assignment as an Expression.
+        symbol_type: The type of symbol, set to SymbolType.GlobalVar.
     """
 
     _left: Expression[Self]

src/codegen/sdk/core/class_definition.py

@@ -51,7 +51,14 @@
 
 @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.
+        _methods: A collection of methods defined in this class.
+    """
 
     symbol_type = SymbolType.Class
     constructor_keyword = None

src/codegen/sdk/core/codebase.py

@@ -106,7 +106,11 @@
 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:
+        _op: The repository operator, which can be either a local or remote repository operator.
+        viz: The visualization manager for the codebase.
+        repo_path: The path to the repository.
+        console: The console used for logging and output.
     """
 
     _op: RepoOperator | RemoteRepoOperator

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

@@ -25,10 +25,11 @@ class Usage:
     """A reference to an exportable object in a file.
 
     Attributes:
-        match: The exact match of the usage
-        usage_symbol: The symbol this object is used in
-        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)
+        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 applicable.
+        usage_type: How this symbol was used.
+        kind: Where this symbol was used (e.g., in a type parameter or in the body of the class).
     """
 
     match: Name | ChainedAttribute | FunctionCall
@@ -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/argument.py

@@ -28,7 +28,11 @@
 
 @apidoc
 class Argument(Expression[Parent], HasName, HasValue, Generic[Parent, TParameter]):
-    """Represents an argument passed into a FunctionCall."""
+    """Represents an argument passed into a FunctionCall.
+
+    Attributes:
+        _pos: The zero-based index of this argument within its parent function call.
+    """
 
     _pos: int
 

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

@@ -45,6 +45,11 @@ 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.
+        _statements: A collection of statements that are part of this code block.
     """
 
     level: int

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

@@ -39,11 +39,10 @@
 
 @apidoc
 class FunctionCall(Expression[Parent], HasName, Resolvable, Generic[Parent]):
-    """Abstract representation of a function invocation, e.g. in Python:
-    ```
-    def f():
-        g()  # FunctionCall
-    ```
+    """Abstract representation of a function invocation.
+
+    Attributes:
+        _arg_list: A collection of arguments passed to the function call.
     """
 
     _arg_list: Collection[Argument, Self]

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

@@ -39,7 +39,12 @@
 
 @apidoc
 class Parameter(Usable[Parent], Typeable[TType, Parent], HasValue, Expression[Parent], Generic[TType, Parent]):
-    """Abstract representation of a parameter in a Function definition."""
+    """Abstract representation of a parameter in a Function definition.
+
+    Attributes:
+        _pos: The 0-based index of this parameter within its parent function's parameter list.
+        _name_node: The node representing the name of the parameter, or None if not applicable.
+    """
 
     _pos: int
     _name_node: Name | None = None

src/codegen/sdk/core/directory.py

@@ -40,6 +40,12 @@
 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: Parent directory, if any.
+        items: 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, which can be another expression or None.
+        right: The right operand of the binary expression, which can be another expression or None.
+    """
 
     left: Expression[Self] | None
     right: Expression[Self] | None

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

@@ -27,8 +27,9 @@
 class ChainedAttribute(Expression[Parent], Resolvable, Generic[Object, Attribute, Parent]):
     """An attribute of an object. (IE a method on a class, a function from a module, etc)
 
-    Examples:
-     A.method()
+    Attributes:
+        _object: The object part of the chained attribute expression.
+        _attribute: The attribute part of the chained attribute expression.
     """
 
     _object: Object

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/generic_type.py

@@ -27,7 +27,11 @@
 
 @apidoc
 class GenericType(NamedType[Parent], Generic[TType, Parent]):
-    """Abstract representation of the generic types of the programming language."""
+    """Abstract representation of the generic types of the programming language.
+
+    Attributes:
+        _parameters: A collection of generic type parameters associated with this type.
+    """
 
     _parameters: Collection[TType, Self]
 

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

@@ -25,8 +25,9 @@ class String(Expression[Parent], Builtin, Generic[Parent]):
     """GraphSitter representation of String.
 
     Attributes:
-        content: The content of the string
-        expressions: embedded expressions in the string, only applicable for templated or formatted strings
+        content: The content of the string.
+        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

@@ -24,6 +24,10 @@
 class SubscriptExpression(Expression[Parent], Resolvable[Parent], Generic[Object, Index, Parent]):
     """Indexing onto an object (Aka using brackets on an object)
 
+    Attributes:
+        object: The object being indexed.
+        indices: A list of indices used for indexing the object.
+
     Examples:
      A[]
     """

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 the node, set to NodeType.EXTERNAL.
     """
 
     node_type: Literal[NodeType.EXTERNAL] = NodeType.EXTERNAL

src/codegen/sdk/core/file.py

@@ -54,6 +54,17 @@ 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.
+        _pending_content_bytes: The pending content of the file in bytes, or None if not set.
+        _directory: The directory containing this file, or None if not set.
+        _pending_imports: A set of pending import strings.
+        _binary: A boolean indicating if the file is binary.
+        _range_index: The range index for the file.
     """
 
     name: str
@@ -430,8 +441,9 @@ class SourceFile(
 ):
     """Represents a file with source code in the codebase.
 
-    Enables creating, reading, updating, and deleting files and searching through their contents,
-    etc.
+    Attributes:
+        code_block: The code block associated with this source file.
+        _nodes: A list of importable nodes 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