Skip to content

PyCodeCommenter — Python Docstring Generator & Validator

Keep Python docstrings accurate as your code evolves.

Deterministic docstring generation and validation for production Python. No AI guesswork — just reliable, rule-based inference that syncs your docs with your AST.

What is PyCodeCommenter?

PyCodeCommenter is an open-source Python tool that:

  1. Generates Google-style docstrings from your code's AST — no AI, no guesswork.
  2. Validates existing docstrings against real function signatures across six check categories.
  3. Measures documentation coverage per file and across entire projects.
  4. Exports structured JSON for integration with any downstream tooling.

Install with: pip install pycodecommenter · Requires Python 3.8+

The Problem & The Solution

Before PyCodeCommenter: Code changes, but docstrings don't. 

def process_data(items, strict=False):
    # Missing 'strict' in docstring. No return type documented.

After PyCodeCommenter: Run $ pycodecommenter generate <path/to/your_file.py> to instantly sync them. 

def process_data(items, strict=False):
    """Process data.

    Args:
        items: The items to process.
        strict: Whether to use strict processing.

    Returns:
        The processed data.
    """

1. Install

pip install pycodecommenter

2. Run

Preview the changes PyCodeCommenter will make to your project without writing to disk:

pycodecommenter generate <path/to/your_file.py> --dry-run

Ready to apply? Write docstrings directly into the file:

pycodecommenter generate <path/to/your_file.py> --inplace

Validate and get a JSON report:

pycodecommenter validate <path/to/your_file.py> --output-format json

3. Explore the Documentation

Getting Started Step-by-step from install to your first generate, validate, and coverage run. Validation Checks All checks — severity levels, violation examples, and how to fix each one. Recipes & CI Pre-commit hooks, GitHub Actions, and coverage gating patterns. CLI Reference Every flag and argument for generate, validate, and coverage — derived directly from the source. Python API Use PyCodeCommenter programmatically: PyCodeCommenter, DocstringValidator, CoverageAnalyzer. FAQ Common questions answered directly from the source code.

Key Facts

Property Value
PyPI package pycodecommenter
Import name PyCodeCommenter
Python support 3.8, 3.9, 3.10, 3.11, 3.12
Output docstring style Google
Input parsing Google (full), Sphinx (partial)
AI / LLM dependency None — fully deterministic
Runtime dependencies stdlib + ruamel.yaml (config only)
License MIT
Version v2.2.0