Auditing Documentation Completeness Across Blocks

🏷️ Final Capstone Engineer Script project / Code Review Checklist

📚 All-in-One📖 Theory Only💻 Code Only

🧭 Context Introduction

When reviewing code, one of the most overlooked aspects is whether the documentation is complete and consistent across all logical blocks. A function might work perfectly, but if its docstring is missing parameters, has outdated descriptions, or skips important details, it becomes a maintenance liability. This audit helps engineers systematically verify that every code block—whether a function, class, or module—has documentation that matches what the code actually does.

🎯 Why Audit Documentation Completeness

Prevents knowledge gaps when team members need to understand or modify code later
Catches mismatches between what the code does and what the documentation claims
Ensures consistency across all blocks so no function is left undocumented
Reduces onboarding time for new team members who rely on clear docs
Supports automated tools like linters and documentation generators

🕵️ What to Check in Each Block

When auditing a code block, verify these documentation elements:

Purpose statement – Does the docstring explain why this block exists?
Parameter descriptions – Are all input parameters listed with types and meanings?
Return value documentation – Is the output clearly described, including type?
Raised exceptions – Are any errors or edge cases documented?
Side effects – Does the block modify global state, write files, or call external services?
Usage examples – Is there a simple example showing how to call the block?

📊 Comparison: Complete vs. Incomplete Documentation

Aspect	✅ Complete Documentation	❌ Incomplete Documentation
Purpose	Clearly states what the block does	Missing or vague one-liner
Parameters	Every parameter listed with type and description	Some parameters missing or undocumented
Return value	Describes output and its type	No return info or incorrect type
Exceptions	Lists all possible errors	No mention of exceptions
Side effects	Documents any external impact	Ignores side effects entirely
Example	Includes a simple usage example	No example provided

🛠️ Practical Audit Checklist

Use this checklist when reviewing any code block:

Read the docstring first – Does it tell you what the block does without reading the code?
Match parameters – Count the parameters in the signature, then count them in the docstring. Do they match?
Verify return statements – Look at every return path in the code. Is each one documented?
Check exception handling – Are there try/except blocks? Are those exceptions mentioned in the docs?
Look for hidden effects – Does the block print to console, write to a file, or modify a global variable? Document it.
Test the example – If an example is provided, does it actually work with the current code?

⚙️ Common Documentation Gaps to Watch For

Missing parameter types – The code expects a string but the docstring doesn't mention it
Outdated return descriptions – The function now returns a dictionary, but the docs still say it returns a list
Silent failures – The code catches exceptions and returns None, but the docs don't mention this behavior
Copy-paste errors – A docstring was copied from another function and still references the wrong parameter names
Missing edge cases – The function handles empty inputs or None values, but the docs don't describe this

📝 Example Audit Walkthrough

Imagine you are reviewing a block that calculates the average of a list of numbers. Here is what a complete audit looks like:

Purpose – The docstring should say: "Calculates the arithmetic mean of a list of numeric values."
Parameters – It should list: numbers (list of float or int) – and describe what happens if the list is empty
Return value – Should state: Returns a float representing the average
Exceptions – Should mention: Raises ValueError if the input list is empty
Side effects – Should note: No side effects – pure function
Example – Should include: average([10, 20, 30]) returns 20.0

If any of these elements are missing or incorrect, that block fails the documentation completeness audit.

📋 Final Review Summary

After auditing all blocks in a script or module, compile a summary like this:

Total blocks reviewed – Count of functions, classes, and modules checked
Fully documented blocks – Those that pass all six checklist items
Partially documented blocks – Those missing one or two elements
Undocumented blocks – Those with no docstring at all
Common issues found – List the top gaps (e.g., missing exception docs, outdated return types)
Action items – Specific fixes needed for each failing block

🚀 Key Takeaway

Documentation completeness is not about writing more words—it is about ensuring that every block's documentation accurately reflects its behavior. By auditing systematically, engineers catch mismatches early, reduce technical debt, and make codebases more maintainable for everyone. A well-documented block is a gift to your future self and your teammates.

This tool checks whether every code block in a Python file has a docstring or comment explaining its purpose.

📝 Example 1: Checking if a single function has a docstring

This example shows how to verify that one function contains a documentation string.

def calculate_load():
    """Returns the structural load in kN."""
    return 450

def has_docstring(func):
    return func.__doc__ is not None

result = has_docstring(calculate_load)
print(result)

📤 Output: True

📝 Example 2: Checking a function missing a docstring

This example demonstrates detecting a function that lacks any documentation.

def calculate_load():
    return 450

def has_docstring(func):
    return func.__doc__ is not None

result = has_docstring(calculate_load)
print(result)

📤 Output: False

📝 Example 3: Auditing a list of functions for docstring completeness

This example shows how to audit multiple functions at once and report which ones are missing documentation.

def calc_area():
    """Calculates area in m²."""
    return 100

def calc_volume():
    return 500

def calc_density():
    """Calculates density in kg/m³."""
    return 1.2

functions = [calc_area, calc_volume, calc_density]

for func in functions:
    has_doc = func.__doc__ is not None
    print(f"{func.__name__}: {'Has docstring' if has_doc else 'Missing docstring'}")

📤 Output: calc_area: Has docstring
calc_volume: Missing docstring
calc_density: Has docstring

📝 Example 4: Auditing classes and their methods for documentation completeness

This example extends the audit to check both class-level and method-level docstrings.

class BeamAnalysis:
    """Analyzes beam deflection under load."""

    def calculate_moment(self):
        """Returns bending moment in kNm."""
        return 200

    def calculate_shear(self):
        return 150

class ColumnAnalysis:
    pass

def audit_class_docs(cls):
    print(f"Class: {cls.__name__}")
    if cls.__doc__ is None:
        print("  - Missing class docstring")
    for name, method in cls.__dict__.items():
        if callable(method):
            if method.__doc__ is None:
                print(f"  - Method '{name}' missing docstring")

audit_class_docs(BeamAnalysis)
audit_class_docs(ColumnAnalysis)

📤 Output: Class: BeamAnalysis
- Method 'calculate_shear' missing docstring
Class: ColumnAnalysis
- Missing class docstring

📝 Example 5: Generating a completeness report for an entire module file

This example reads a Python file and reports which top-level blocks (functions and classes) are missing documentation.

import ast

def audit_file(filepath):
    with open(filepath, "r") as f:
        tree = ast.parse(f.read())

    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.ClassDef)):
            name = node.name
            has_doc = (ast.get_docstring(node) is not None)
            status = "Complete" if has_doc else "Missing"
            print(f"{type(node).__name__} '{name}': Documentation {status}")

# Assume we have a file named 'structure_analysis.py' with:
# def calc_load(): ...
# class Beam: ...
audit_file("structure_analysis.py")

📤 Output: FunctionDef 'calc_load': Documentation Complete
ClassDef 'Beam': Documentation Missing

Comparison Table: Documentation Audit Approaches

Approach	Scope	Output Detail	Use Case
Single function check	One function	Boolean	Quick verification
List of functions	Multiple functions	Per-function status	Small module audit
Class and method audit	One class	Per-method status	Object-oriented code review
Full file AST audit	Entire module	Per-block status	Pre-commit or CI pipeline check