Docstring Coverage Solution

Problem

The NoDupeLabs codebase contained functions without docstrings. Standard regex-based approaches could not handle these patterns:

Functions with comments as first statement
Functions with control flow (if, try, with) as first statement
Nested function definitions
Multi-line function signatures

Approach

Key Implementation Detail

The script inserts docstrings immediately after the function definition line:

# Insert right after def line, before any other content
lines.insert(func_line_idx + 1, docstring)

This works because Python considers comments as non-statements. A docstring inserted after the def line becomes the first statement in the function body.

Technical Details

The solution uses Python's AST module to:

Parse each Python file
Identify functions without docstrings
Calculate correct indentation based on function definition
Insert docstring at the correct position

for node in ast.walk(tree):
    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
        has_docstring = (
            node.body and
            isinstance(node.body[0], ast.Expr) and
            isinstance(node.body[0].value, ast.Constant) and
            isinstance(node.body[0].value.value, str)
        )

Usage

# Preview changes
python fix_docstrings.py nodupe/

# Apply changes
python fix_docstrings.py --apply nodupe/

Results

Metric	Before	After
Module Docstrings	75/78	78/78
Class Docstrings	221/221	222/222
Function Docstrings	1015/1182	1182/1182

Files modified: 25 Functions updated: 167

Compliance

The solution produces valid Python that satisfies PEP 257 requirements:

Docstrings appear as first statement in function bodies
Indentation matches function body level
Multi-line signatures handled correctly

Script Location

The working script is available as fix_docstrings.py in the project root.

2 KiB Raw Blame History