mirror of
https://github.com/allaunthefox/Research-Stack.git
synced 2026-07-31 03:05:21 +00:00
73 lines
2 KiB
Markdown
73 lines
2 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
# 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:
|
|
1. Parse each Python file
|
|
2. Identify functions without docstrings
|
|
3. Calculate correct indentation based on function definition
|
|
4. Insert docstring at the correct position
|
|
|
|
```python
|
|
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
|
|
|
|
```bash
|
|
# 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.
|