docstring-coverage（文档字符串覆盖率）

Docstring Coverage for Git Diff

Add comprehensive docstrings to all functions, methods, and classes that were added or modified in the current git diff. Supports Python, JavaScript/TypeScript, Java, Kotlin, Go, Rust, Ruby, C/C++/C#, Swift, PHP, Scala, Elixir, Lua, and Shell.

Workflow

Step 1: Identify the Diff Scope

Determine what the user wants documented. Ask if unclear, otherwise default to staged + unstaged changes.

# Priority order — use the first that matches the user's intent:

# 1. Changes in a PR branch vs main/master
git diff main...HEAD

# 2. All uncommitted changes (staged + unstaged) — DEFAULT
git diff HEAD

# 3. Only staged changes
git diff --cached

# 4. Last N commits
git diff HEAD~N..HEAD

# 5. Specific commit
git diff <commit>^..<commit>

Store the chosen diff for the rest of the workflow.

Step 2: Extract Changed Symbols

Parse the diff to find all functions, methods, and classes that were added or modified. Focus on:

• New functions/methods (lines starting with + that define a function)
• Modified functions/methods (functions in hunks that have changes)
• New classes (class definitions in added lines)

Ignore: deleted code, import changes, variable assignments, comments-only changes.

Symbol Detection: Refer to the language-specific files in languages/ for regex patterns to identify symbols. See the Routing Table below to find the correct file.

Step 3: Read Full Context

For each changed symbol, read the full current file (not just the diff) to understand:

• The function signature and parameters
• The return type/value
• What the function body does
• How it fits into the broader module
• Any exceptions/errors raised
• Side effects

This context is critical for writing accurate docstrings.

Step 4: Generate Docstrings

For each symbol missing a docstring or having an outdated one, write a docstring following the project's existing conventions.

Convention Detection:

1. Detect Style: Scan the codebase for existing docstrings to identify the dominant style.
2. Read conventions.md: Check this file for detailed rules on convention auto-detection priorities and cross-language edge cases.
3. Language Routing: Use the project's detected language(s) to load the appropriate file from languages/.

Docstring quality rules:

• First line: A concise one-line summary of what the function does (imperative mood: "Calculate...", "Return...", "Validate...")
• Parameters: Document every parameter with name, type (if not in signature), and description
• Returns: Document what the function returns, including type
• Raises/Throws: Document exceptions that can be raised
• No fluff: Don't restate the function name. Don't say "This function..." — just describe what it does
• Be specific: Prefer "Calculate the Euclidean distance between two 2D points" over "Perform calculation"
• Edge cases: Mention important edge case behavior (e.g., "Returns None if the list is empty")

Step 5: Apply Changes

Apply the docstrings directly to the source files. Use precise edits — do NOT rewrite entire files. For each symbol:

1. Locate the function/method/class definition in the file
2. Check if a docstring already exists

- If yes and it's outdated/incomplete: update it - If yes and it's accurate: skip it - If no: insert one

1. Apply the edit

Step 6: Summary Report

After applying all docstrings, output a summary:

## Docstring Coverage Report

**Scope**: `git diff HEAD` (uncommitted changes)
**Files scanned**: 7
**Symbols found in diff**: 12
**Docstrings added**: 8
**Docstrings updated**: 2
**Already documented**: 2

### Changes by file:
- `src/auth/token.py` — added docstrings to `generate_token()`, `validate_token()`, `refresh_token()`
- `src/api/handlers.py` — added docstring to `UserHandler` class, updated `handle_request()`
- `src/utils/math.py` — added docstrings to `normalize()`, `clamp()`, `lerp()`

Edge Cases

• Decorators: Place docstring after the function def line, not after decorators
• Overloaded methods: Document the primary signature; note overloads
• Property getters/setters: Document the property, not individual get/set
• One-liners: Still add a one-line docstring even for simple functions
• Test functions: Use a lighter style — one line describing what's being tested
• Private/internal functions (e.g., _helper()): Still document, but can be briefer
• Lambda functions: Skip — these can't have docstrings
• Already well-documented: Don't touch it. Only update if the signature changed but the docstring didn't reflect it.

Language-Specific Details

Routing Logic: Based on the language(s) detected in the project, refer to the corresponding file in the languages/ directory.

Routing Table

Map the file extension to the correct language definition file:

For cross-language rules (linting, generated code, encoding), see conventions.md.