find-documentation-gaps

TODAY=!date +%Y-%m-%d

Documentation Gaps

Identifies public-facing code — functions, classes, modules, CLI commands, REST endpoints, and config options — that is missing or has stale documentation. Ranks gaps by how visible and heavily-used the surface area is, so the most impactful docs get written first.

Prerequisites

• Working directory is the root of the repository
• Optional: $1 — path to limit the scan (defaults to .)
• Optional language-specific tools:
  • Python: interrogate (uv tool install interrogate) for docstring coverage
  • JavaScript/TypeScript: typedoc or jsdoc comment detection via rg
  • Go: golint or rg for unexported godoc

What Counts as a Documentation Gap

Steps

1. Detect Language and Project Type

find ${1:-.} -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10
ls README* docs/ CHANGELOG* openapi* swagger* 2>/dev/null

2. Measure Docstring / Comment Coverage

Python — interrogate:

interrogate ${1:-.} -v --ignore-init-method --ignore-magic --ignore-private 2>/dev/null | tail -30

Flag any module, class, or function with MISSING in the output.

Python — rg fallback:

# Find public functions/classes with no immediately following docstring
python3 -c "
import ast, sys, os
for root, dirs, files in os.walk('${1:-.}'):
    dirs[:] = [d for d in dirs if not d.startswith('.') and d not in ('__pycache__', '.venv', 'node_modules')]
    for f in files:
        if not f.endswith('.py'): continue
        path = os.path.join(root, f)
        try:
            tree = ast.parse(open(path).read())
        except:
            continue
        for node in ast.walk(tree):
            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
                if node.name.startswith('_'): continue
                if not (node.body and isinstance(node.body[0], ast.Expr) and isinstance(node.body[0].value, ast.Constant)):
                    print(f'{path}:{node.lineno}  {type(node).__name__}  {node.name}')
" 2>/dev/null | head -50