Graph-sitter enables reading, modifying, and manipulating comments and docstrings while preserving proper formatting.

This guide describes proper usage of the following classes:

​
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. Graph-sitter 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

Graph-sitter 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

Graph-sitter 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, Graph-sitter automatically handles indentation and maintains the existing comment style.

​
Special APIs and AI Integration

​
Google Style Docstrings

Graph-sitter 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

Graph-sitter 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.