Graph-sitter enables reading, modifying, and manipulating comments and docstrings while preserving proper formatting.
This guide describes proper usage of the following classes:
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)
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")
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
""")
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.
""")
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)
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.