Skip to content

Commit f06005e

Browse files
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
1 parent 2026481 commit f06005e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+314
-98
lines changed

src/codegen/git/models/pr_options.py

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,14 @@
55

66
@apidoc
77
class PROptions(BaseModel):
8-
"""Options for generating a PR."""
8+
"""Options for generating a PR.
9+
10+
Attributes:
11+
title: The title of the pull request.
12+
body: The body content of the pull request.
13+
labels: A list of labels to be added to the pull request.
14+
force_push_head_branch: Whether to force push the head branch.
15+
"""
916

1017
title: str | None = None
1118
body: str | None = None

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

Lines changed: 32 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,25 @@
99
from codegen.sdk.core.codebase import Codebase
1010
from codegen.sdk.core.placeholder.placeholder_type import TypePlaceholder
1111

12-
ATTRIBUTES_TO_IGNORE = ["G", "node_id", "angular"]
13-
14-
15-
def generate_docs_json(codebase: Codebase, head_commit: str) -> dict[str, dict[str, Any]]:
12+
ATTRIBUTES_TO_IGNORE = [
13+
"G",
14+
"node_id",
15+
"angular",
16+
"model_config",
17+
"constructor_keyword",
18+
"viz",
19+
"console",
20+
"items",
21+
"node_type",
22+
"ts_node",
23+
"file_node_id",
24+
"G",
25+
"statement_type",
26+
"assignment_types",
27+
]
28+
29+
30+
def generate_docs_json(codebase: Codebase, head_commit: str, raise_on_missing_docstring: bool = False) -> dict[str, dict[str, Any]]:
1631
"""Update documentation table for classes, methods and attributes in the codebase.
1732
1833
Args:
@@ -23,7 +38,6 @@ def generate_docs_json(codebase: Codebase, head_commit: str) -> dict[str, dict[s
2338
"""
2439
codegen_sdk_docs = GSDocs(classes=[])
2540
types_cache = {}
26-
attr_cache = {}
2741

2842
def process_class_doc(cls):
2943
"""Update or create documentation for a class."""
@@ -110,22 +124,22 @@ def process_attribute(attr, cls, cls_doc, seen_methods):
110124
return
111125

112126
attr_path = create_path(attr, cls)
113-
original_attr_path = create_path(attr)
114127

115-
if original_attr_path not in attr_cache:
116-
description = attr.docstring(cls)
117-
attr_return_type = []
118-
if r_type := get_type_str(attr):
119-
if isinstance(r_type, TypePlaceholder):
120-
resolved_types = []
121-
else:
122-
resolved_types = r_type.resolved_types
123-
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)
124-
attr_return_type.append(r_type_source)
128+
description = attr.docstring(attr.parent_class)
129+
if raise_on_missing_docstring and not description:
130+
msg = f"Attribute {attr.parent_class.name}.{attr.name} does not have a docstring"
131+
raise ValueError(msg)
132+
attr_return_type = []
133+
if r_type := get_type_str(attr):
134+
if isinstance(r_type, TypePlaceholder):
135+
resolved_types = []
136+
else:
137+
resolved_types = r_type.resolved_types
138+
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)
139+
attr_return_type.append(r_type_source)
125140

126-
attr_cache[original_attr_path] = {"description": description, "attr_return_type": attr_return_type}
141+
attr_info = {"description": description, "attr_return_type": attr_return_type}
127142

128-
attr_info = attr_cache[original_attr_path]
129143
meta_data = {"parent": create_path(attr.parent_class), "path": attr.file.filepath}
130144

131145
return MethodDoc(

src/codegen/sdk/codebase/span.py

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,12 @@ def range_json_schema() -> JsonSchemaValue:
5454

5555
@apidoc
5656
class Span(BaseModel):
57-
"""Range within the codebase"""
57+
"""Range within the codebase
58+
59+
Attributes:
60+
range: Adapter for the range within the codebase.
61+
filepath: The path to the file associated with the range.
62+
"""
5863

5964
model_config = ConfigDict(
6065
frozen=True,

src/codegen/sdk/core/assignment.py

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,15 +45,14 @@
4545
class Assignment(Symbol[Parent, ...], Typeable[Parent, ...], HasValue, Generic[Parent]):
4646
"""Represents an assignment for a single variable within an assignment statement.
4747
48-
Attributes:
49-
left: The left side of the assignment
50-
right: The right side of the assignment
51-
5248
Example:
5349
```typescript
5450
var z
5551
var z = 5
5652
```
53+
54+
Attributes:
55+
symbol_type: The type of symbol, set to SymbolType.GlobalVar.
5756
"""
5857

5958
_left: Expression[Self]

src/codegen/sdk/core/class_definition.py

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,13 @@
5151

5252
@apidoc
5353
class Class(Inherits[TType], HasBlock[TCodeBlock, TDecorator], Callable[TParameter, TType], HasAttribute[TFunction | Attribute], Generic[TFunction, TDecorator, TCodeBlock, TParameter, TType]):
54-
"""Abstract representation of a Class definition."""
54+
"""Abstract representation of a Class definition.
55+
56+
Attributes:
57+
symbol_type: The type of symbol, set to SymbolType.Class.
58+
constructor_keyword: The keyword used to identify the constructor method.
59+
parent_classes: The parent classes of this class, if any.
60+
"""
5561

5662
symbol_type = SymbolType.Class
5763
constructor_keyword = None

src/codegen/sdk/core/codebase.py

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,10 @@
106106
class Codebase(Generic[TSourceFile, TDirectory, TSymbol, TClass, TFunction, TImport, TGlobalVar, TInterface, TTypeAlias, TParameter, TCodeBlock]):
107107
"""This class provides the main entrypoint for most programs to analyzing and manipulating codebases.
108108
109-
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.
109+
Attributes:
110+
viz: Manages visualization of the codebase graph.
111+
repo_path: The path to the repository.
112+
console: Manages console output for the codebase.
110113
"""
111114

112115
_op: RepoOperator | RemoteRepoOperator

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

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ class Usage:
2727
Attributes:
2828
match: The exact match of the usage
2929
usage_symbol: The symbol this object is used in
30+
imported_by: The import statement that brought this symbol into scope, or None if not imported
3031
usage_type: How this symbol was used
3132
kind: Where this symbol was used (IE: in a type parameter or in the body of the class, etc)
3233
"""
@@ -62,15 +63,17 @@ class UsageKind(IntEnum):
6263
6364
Attributes:
6465
SUBCLASS: Used in symbol inheritance.
65-
TYPE_ANNOTATION: Used as a type annotation on a parameter or assignment statement.
66+
TYPED_PARAMETER: Used as a typed parameter in a function/method.
67+
TYPE_ANNOTATION: Used as a type annotation on a parameter or assignment statement.
6668
BODY: Usage within the body of a function/method.
6769
DECORATOR: Usage within a decorator.
68-
RETURN_TYPE: Used as a return type annotation
70+
RETURN_TYPE: Used as a return type annotation.
6971
TYPE_DEFINITION: Used in a type alias.
7072
EXPORTED_SYMBOL: Used in an export statement.
7173
EXPORTED_WILDCARD: Re-exported by a wildcard export.
7274
GENERIC: Used as a type parameter to another type.
7375
IMPORTED: Imported with an import statement.
76+
IMPORTED_WILDCARD: Imported with a wildcard import statement.
7477
DEFAULT_VALUE: Represents a default value in a function/method parameter.
7578
"""
7679

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,10 @@ class CodeBlock(Expression[Parent], Generic[Parent, TAssignment]):
4545
function body or class body.
4646
4747
Enables various types of queries and operations on the code block.
48+
49+
Attributes:
50+
level: The indentation level of the code block.
51+
parent_block: The parent code block containing this block, or None if it is a top-level block.
4852
"""
4953

5054
level: int

src/codegen/sdk/core/directory.py

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,14 @@
3939
@apidoc
4040
class Directory(Generic[TFile, TSymbol, TImportStatement, TGlobalVar, TClass, TFunction, TImport]):
4141
"""Directory representation for codebase.
42+
4243
GraphSitter abstraction of a file directory that can be used to look for files and symbols within a specific directory.
44+
45+
Attributes:
46+
path: Absolute path of the directory.
47+
dirpath: Relative path of the directory.
48+
parent: The parent directory, if any.
49+
items: A dictionary containing files and subdirectories within the directory.
4350
"""
4451

4552
path: Path # Absolute Path

src/codegen/sdk/core/export.py

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,11 @@
2121

2222
@apidoc
2323
class Export(Exportable[Parent], Generic[Parent]):
24-
"""Represents a single symbol being exported."""
24+
"""Represents a single symbol being exported.
25+
26+
Attributes:
27+
export_statement: The statement representing the export.
28+
"""
2529

2630
export_statement: ExportStatement
2731

0 commit comments

Comments
 (0)