doxygen-guard

Pre-commit hook that enforces doxygen documentation and reports the change impact of what you commit. Language- and architecture-agnostic.

Scope is deliberately narrow: enforcement and impact. Diagram generation and symbol indexing are out of scope — see Consumer Contract for the machine-readable surface that downstream tools build on.

Quick Start

1. Add the hook to .pre-commit-config.yaml

repos:
  - repo: https://github.com/tvanfossen/doxygen-guard
    rev: main
    hooks:
      - id: doxygen-guard
        types_or: [c, c++, java, python]

2. Create .doxygen-guard.yaml in your repo root

output_dir: docs/generated/

validate:
  exclude:
    - "^tests/"
    - "^\\.venv/"
  tags:
    req:
      pattern: "^REQ-[A-Z]+-[0-9]{3}$"
  version_gate:
    current_version: "auto:git"
    version_field: "min_version"

impact:
  requirements:
    file: docs/requirements.yaml
    format: yaml

3. Add doxygen to your functions

/**
 * @brief Read temperature from sensor hardware.
 * @version 1.0
 * @req REQ-SENSE-001
 * @return Raw ADC value
 */
int Sensor_ReadTemperature(void) {
    return hw_read_adc(TEMP_CHANNEL);
}

Run pre-commit run --all-files — violations print to stderr and the impact report appears in <output_dir>/impact/.

What It Does

Validation (pre-commit gate)

Every function in staged files is checked for:

• Presence — must have @brief, @version, and @return (non-void functions)
• Version staleness — if function body changed (git diff), @version must be updated
• Tag syntax — tag values validated against configured patterns
• Requirement coverage — functions must have @req or an exemption tag

Exemption Tags

Change-Impact Reports

Cross-references git diff with parsed functions to show which requirements are affected by staged changes. Reports in markdown and JSON at <output_dir>/impact/.

Requirement Coverage

doxygen-guard coverage cross-references @req tags against the catalog and reports covered, uncovered and orphan requirements, plus documented functions carrying no @req. Exit code 1 when gaps exist.

Configuration Reference

validate section

impact section

These defaults are also emitted by doxygen-guard config --schema. Read them from there rather than copying them — see Consumer Contract.

Requirements catalog

The preferred form is a mapping keyed by requirement ID. The ID is the key, so no id_column applies:

requirements:
  REQ-VAL-001:
    name: Doxygen presence check      # required
    subsystem: Validate               # optional
    min_version: v0.1.0               # optional
    description: >-                   # optional
      Every function must have a doxygen comment
    acceptance_criteria: >-           # optional
      Undocumented functions produce presence violations

The catalog is validated on load. A missing file, an unknown format, a wrong document shape, a missing name, or an ID failing validate.tags.req.pattern each raise RequirementsError — the run fails rather than silently proceeding with an empty catalog. Flat csv/json row formats remain supported and use id_column.

Consumer Contract

Tools built on doxygen-guard must read the contract from the tool, not re-derive it. Every declaration the gate honours is observable in this output.

doxygen-guard config --schema       # schema, defaults, catalog constants, contract_version
doxygen-guard config --effective    # the merged config in force and what it resolved to
doxygen-guard files src/            # the exact post-exclude file set the gate walks

All three emit JSON carrying a contract_version. Compare it against the value your tool was written for; when it moves, re-check your assumptions.

doxygen-guard files is the authoritative answer to "which files does the gate consider?" — it applies validate.exclude exactly as validation does. A consumer that walks the tree itself and diffs against this output will detect its own divergence instead of silently reporting on files the gate never sees.

Typed errors are importable from doxygen_guard.errors: GuardError with ConfigError and RequirementsError subclasses. load_config raises rather than exiting, so in-process callers can handle failures; exit codes are produced only at the CLI boundary.

Passthrough config

Consumers may declare their own sections in .doxygen-guard.yaml using an x- prefix, at any nesting level. The guard validates that they parse but never interprets them:

x-my-tool:
  index_path: .cache/index

Any other unknown key is an error.

File-Level Doxygen

Each source file should have a file-level doxygen block:

/**
 * @file
 * @brief Sensor hardware abstraction layer.
 * @version 1.0
 */

Enable validate.presence.require_file_doxygen: true to enforce file-level blocks.

For Python:

## @file
## @brief Configuration loading and validation.
## @version 1.0

Python Function Docstring Style

Python functions accept doxygen tags in two equivalent forms. Use whichever fits your codebase — they are interchangeable on a per-function basis.

Two-hash block above the def (classic doxygen-for-Python convention):

## @brief Apply a unified-diff patch to a project directory.
#  @version 1.0
#  @req REQ-PATCH-001
#  @return 0 on success, non-zero on failure.
def apply_patch(repo_path: str, patch: str) -> int:
    ...

Inside the PEP 257 docstring (idiomatic Python — Sphinx/IDE-friendly):

def apply_patch(repo_path: str, patch: str) -> int:
    """Apply a unified-diff patch via `git apply`.

    @brief Apply a unified-diff patch to a project directory.
    @version 1.0
    @req REQ-PATCH-001
    @return 0 on success, non-zero on failure.
    """
    ...

When both styles are present on the same function, the ##-block above takes precedence. A docstring without any recognized tag is not treated as a doxygen block (so prose-only docstrings remain free-form).

Config Validation

The config file is validated at load time against a built-in schema. Unknown keys are rejected, with a suggestion when one is close:

doxygen-guard: Invalid config in .doxygen-guard.yaml
Unknown config key: validate.exclud — did you mean 'exclude'?

Keys prefixed x- are exempt (see Passthrough config). The schema itself is available via doxygen-guard config --schema.

Escaping @ in Documentation Text

As in doxygen itself, @word is a command anywhere in a block — including mid-sentence. To mention a tag name in prose, escape it as \@ or @@:

/**
 * @brief Rows carry their declared \@req IDs.
 * @version 1.0
 */

Without the escape, @req IDs parses as a req tag valued IDs, and the gate reports a requirement that does not exist.

Adopting on an Existing Codebase

For repos with existing code that has no doxygen, adopt incrementally:

1. Start with validation only — add @brief and @version to functions as you touch them. Use version_gate to only enforce @req on functions added after a specific version:

validate:
  version_gate:
    current_version: "auto:git"
    version_field: "min_version"

2. Add @return to non-void functions — required by default. Disable with presence.require_return: false during migration.

3. Exclude paths you're not ready to cover:

validate:
  exclude:
    - "^vendor/"
    - "^legacy/"

Supported Languages

C++ template functions (template<typename T> void func(...)) are fully supported — doxygen comments are associated via tree-sitter AST sibling detection, handling template_declaration wrappers correctly.

CLI Usage

# Pre-commit mode (default — called by pre-commit)
doxygen-guard [--config path] [files...]

# Explicit subcommands
doxygen-guard validate --no-git src/*.c
doxygen-guard impact --staged src/*.c
doxygen-guard coverage src/

# Consumer contract (JSON)
doxygen-guard config --schema
doxygen-guard config --effective
doxygen-guard files src/

# Verbose mode — logs which config sections were declared vs defaulted
doxygen-guard -v coverage src/

Scope and Direction

The tool is feature-complete for what it does: enforcement and change impact. See ROADMAP.md for what is being considered, what is explicitly out of scope, and the three tests any new feature has to pass.

License

MIT — see LICENSE.