Code Documenter

Code Documenter is an AI skill that generates comprehensive, accurate documentation for codebases including function docstrings, module descriptions, API references, and architecture overviews. It covers inline documentation, API reference generation, README creation, changelog maintenance, and documentation testing that keeps documentation synchronized with the code it describes.

What Is This?

Overview

Code Documenter provides automated and semi-automated documentation generation for software projects. It addresses function and class docstring generation with parameter descriptions and return types, module-level documentation explaining purpose and usage patterns, API reference pages generated from code annotations, README files with installation, usage, and contribution guidelines, changelog entries that summarize changes between releases, and documentation accuracy testing that verifies examples still work.

Who Should Use This

This skill serves developers who need to document existing codebases, library authors creating API reference documentation, team leads establishing documentation standards, and open source maintainers improving project accessibility through better documentation.

Why Use It?

Problems It Solves

Codebases without documentation force developers to read source code to understand usage, which is slow and error-prone. Outdated documentation is worse than no documentation because it misleads users. Manual documentation efforts fall behind as code evolves. Inconsistent documentation styles across a project create confusion.

Core Highlights

The skill generates documentation that matches the actual code signature and behavior. Docstring templates follow language-specific conventions like Google style for Python or JSDoc for JavaScript. Automated checks verify that documented examples produce expected outputs. Generated documentation integrates with popular documentation site generators.

How to Use It?

Basic Usage

def generate_docstring(func_source):
    """Generate a docstring for a Python function from its source code."""
    import ast
    tree = ast.parse(func_source)
    func_def = tree.body[0]

    params = []
    for arg in func_def.args.args:
        annotation = ""
        if arg.annotation:
            annotation = f" ({ast.unparse(arg.annotation)})"
            params.append(f"        {arg.arg}{annotation}: Description.")

    returns = ""
    if func_def.returns:
        returns = f"\n    Returns:\n        {ast.unparse(func_def.returns)}: Description."

    docstring = f'"""Brief description of {func_def.name}.\n\n'
    if params:
        docstring += "    Args:\n" + "\n".join(params) + "\n"
    docstring += returns + '\n    """'
    return docstring

Real-World Examples

class DocumentationGenerator:
    def __init__(self, project_path):
        self.path = project_path
        self.modules = self.discover_modules()

    def generate_api_reference(self):
        reference = {}
        for module in self.modules:
            classes = self.extract_classes(module)
            functions = self.extract_functions(module)
            reference[module.name] = {
                "description": module.docstring or "No description",
                "classes": [{"name": c.name, "methods": self.document_methods(c),
                             "docstring": c.docstring} for c in classes],
                "functions": [{"name": f.name, "signature": f.signature,
                               "docstring": f.docstring} for f in functions]
            }
        return reference

    def check_documentation_coverage(self):
        total = 0
        documented = 0
        for module in self.modules:
            for item in self.get_public_items(module):
                total += 1
                if item.docstring:
                    documented += 1
        coverage = documented / total * 100 if total > 0 else 0
        return {"total": total, "documented": documented, "coverage": f"{coverage:.1f}%"}

Advanced Tips

Implement documentation coverage checks in CI that fail the build when coverage drops below a threshold. Generate documentation from type annotations and test cases when manual documentation is missing. Use documentation testing tools like doctest to verify code examples remain accurate as the codebase evolves.

When to Use It?

Use Cases

Use Code Documenter when onboarding new developers to a project that lacks documentation, when preparing a library for public release and needing API references, when establishing documentation standards for a development team, or when auditing documentation coverage to identify gaps.

Related Topics

Sphinx and MkDocs for documentation site generation, JSDoc and TypeDoc for JavaScript documentation, Swagger/OpenAPI for API documentation, and doctest for documentation verification all complement code documentation workflows.

Important Notes

Requirements

Access to the source code files that need documentation. A documentation style convention chosen for the project, such as Google style or NumPy style docstrings. A documentation generation tool compatible with the chosen style.

Usage Recommendations

Do: document the why behind complex logic, not just the what, since code already shows what it does. Keep documentation close to the code it describes to reduce synchronization overhead. Include usage examples in docstrings so developers can copy and adapt them.

Don't: generate verbose documentation for self-explanatory functions like simple getters. Write documentation that paraphrases the function name without adding meaningful context. Let automated generation replace human review of documentation accuracy.

Limitations

Automated documentation generation captures structure and signatures but may miss the intent behind design decisions. Generated descriptions for complex algorithms may be superficial without domain expertise. Documentation testing verifies syntax and basic execution but cannot verify that explanations are clear and helpful to readers.