Comments and Docstrings

Codegen enables reading, modifying, and manipulating comments and docstrings while preserving proper formatting.

This guide describes proper usage of the following classes:

• Comment - Represents a single comment.
• CommentGroup - Represents a group of comments.

Accessing with Comments

Comments can be accessed through any symbol or directly from code blocks. Each comment is represented by a Comment object that provides access to both the raw source and parsed text:

# Find all comments in a file
file = codebase.get_file("my_file.py")
for comment in file.code_block.comments:
    print(comment.text)

# Access comments associated with a symbol
symbol = file.get_symbol("my_function")
if symbol.comment:
    print(symbol.comment.text)  # Comment text without delimiters
    print(symbol.comment.source)  # Full comment including delimiters

# Access inline comments
if symbol.inline_comment:
    print(symbol.inline_comment.text)

# Accessing all comments in a function
for comment in symbol.code_block.comments:
    print(comment.text)

Editing Comments

Comments can be modified using the edit_text() method, which handles formatting and delimiters automatically:

# Edit a regular comment
symbol.comment.edit_text("Updated comment text")

# Edit an inline comment
symbol.set_inline_comment("New inline comment")

Comment Groups

Multiple consecutive comments are automatically grouped into a CommentGroup, which can be edited as a single unit:

# Original comments:
# First line
# Second line
# Third line

comment_group = symbol.comment
print(comment_group.text)  # "First line\nSecond line\nThird line"

# Edit the entire group at once
comment_group.edit_text("New first line\nNew second line")

Working with Docstrings

Docstrings are special comments that document functions, classes, and modules. Codegen provides similar APIs for working with docstrings:

function = file.get_symbol("my_function")
if function.docstring:
    print(function.docstring.text)  # Docstring content
    print(function.docstring.source)  # Full docstring with delimiters

Adding Docstrings

You can add docstrings to any symbol that supports them:

# Add a single-line docstring
function.set_docstring("A brief description")

# Add a multi-line docstring
function.set_docstring("""
    A longer description that
    spans multiple lines.

    Args:
        param1: Description of first parameter
""")

Language-Specific Formatting

Codegen automatically handles language-specific docstring formatting:

# Python: Uses triple quotes
def my_function():
    """Docstring is formatted with triple quotes."""
    pass

// TypeScript: Uses JSDoc style
function myFunction() {
  /** Docstring is formatted as JSDoc */
}

Editing Docstrings

Like comments, docstrings can be modified while preserving formatting:

# Edit a docstring
function.docstring.edit_text("Updated documentation")

# Edit a multi-line docstring
function.docstring.edit_text("""
    Updated multi-line documentation
    that preserves indentation and formatting.
""")

Comment Operations

Codegen provides utilities for working with comments at scale. For example, you can update or remove specific types of comments across your codebase:

# Example: Remove eslint disable comments for a specific rule
for file in codebase.files:
    for comment in file.code_block.comments:
        if "eslint-disable" in comment.source:
            # Check if comment disables specific rule
            if "@typescript-eslint/no-explicit-any" in comment.text:
                comment.remove()

When editing multi-line comments or docstrings, Codegen automatically handles indentation and maintains the existing comment style.

Special APIs and AI Integration

Google Style Docstrings

Codegen supports Google-style docstrings and can handle their specific formatting, using the CommentGroup.to_google_docstring(…) method.

# Edit while preserving Google style
symbol_a = file.get_symbol("SymbolA")
func_b = symbol_a.get_method("funcB")
func_b.docstring.to_google_docstring(func_b)

Using AI for Documentation

Codegen integrates with LLMs to help generate and improve documentation. You can use the Codebase.ai(…) method to:

• Generate comprehensive docstrings
• Update existing documentation
• Convert between documentation styles
• Add parameter descriptions

# Generate a docstring using AI
function = codebase.get_function("my_function")

new_docstring = codebase.ai(
    "Generate a comprehensive docstring in Google style",
    target=function
    context={
        # provide additional context to the LLM
        'usages': function.usages,
        'dependencies': function.dependencies
    }
)
function.set_docstring(new_docstring)

Learn more about AI documentation capabilities in our Documentation Guide and LLM Integration Guide.

Documentation Coverage

You can analyze and improve documentation coverage across your codebase:

# Count documented vs undocumented functions
total = 0
documented = 0
for function in codebase.functions:
    total += 1
    if function.docstring:
        documented += 1

coverage = (documented / total * 100) if total > 0 else 0
print(f"Documentation coverage: {coverage:.1f}%")

Check out the Documentation Guide for more advanced coverage analysis and bulk documentation generation.