Skip to main content

doxygen-guard

Pre-commit hook that validates doxygen comments, generates PlantUML sequence diagrams, and produces change-impact reports. Architecture-agnostic — works with event-driven, sequential, async IPC, and any other pattern.

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/"

trace:
  format: plantuml
  participant_field: "Subsystem"
  static_participants:
    - name: User
      type: actor
  external:
    - Cloud:
        receives_prefix: ["MQTT:"]
        boundary_functions: ["CloudMgr_Publish"]
        label_template: "MQTT: {arg0}"
        entry_chain:
          - { from: User, to: Mobile, label: "{req_name}" }
          - { from: Mobile, to: Cloud, label: "{req_name}" }
    - MCU:
        receives_prefix: ["DURABLE:"]
        boundary_functions: ["DurableEventCb"]
  options:
    show_returns: false
    label_mode: brief

impact:
  requirements:
    file: docs/requirements.csv
    id_column: "Req ID"
    name_column: "Name"
    format: csv

3. Add doxygen to your functions

/** @participant Sensor Driver */

/**
 * @brief Read temperature from sensor hardware.
 * @version 1.0
 * @req REQ-0010
 * @return Raw ADC value
 */
int Sensor_ReadTemperature(void) {
    int raw = hw_read_adc(TEMP_CHANNEL);
    event_post(EVENT_SENSOR_DATA_READY, raw);
    return raw;
}

Run pre-commit run --all-files — diagrams appear in docs/generated/sequences/.

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

Sequence Diagrams (auto-generated)

Behavioral sequence diagrams are generated from annotations. Most tags are inferred from AST:

Tag Purpose Manual?
@req Requirement mapping Yes — per function
@participant Participant identity Yes — once per file
@note Diagram notes (doxygen built-in) Yes — per function
@after Precondition cross-reference Yes — per function
@loop Wrap handler in loop block Yes — per function
@group Wrap handler in group block Yes — per function
@return Return value documentation Yes — per function
@send_source Infrastructure root (e.g., on Event_post) Yes — once
@receive_source Registration root (e.g., on Event_register) Yes — once
@sends Events emitted Inferred from AST
@receives Events handled Inferred from AST
@calls Cross-module boundary calls Inferred from AST

The tool scans function bodies via tree-sitter to detect event_post() calls, Event_register() patterns, and cross-participant function calls automatically.

Diagram Features

  • Entry chains — upstream participant arrows (User→Mobile→Cloud) prepended from config
  • Label templates — protocol labels from boundary function args (MQTT: {arg0})
  • Hub backtracking — REQs routed through dispatch hubs get entry chains automatically
  • Control flow blocks (if/else, loops) from AST
  • Loop/group wrappers — @loop and @group tags for repeated/grouped handlers
  • Boundary argument extraction — function args rendered on arrows via tree-sitter
  • Incremental generation — SHA-256 manifest skips unchanged diagrams

Exemption Tags

Tag Validation Trace
@internal Exempt from @req Invisible — never in any diagram
@utility Exempt from @req Visible — appears as call target
@callback Exempt from @req Normal visibility

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/.

Configuration Reference

validate section

Key Type Default Description
languages dict C, C++, Java, Python Per-language function patterns and comment styles
presence.require_doxygen bool true Require doxygen on every function
presence.require_return bool true Require @return on non-void functions
presence.skip_forward_declarations bool true Skip C/C++ forward declarations
version.require_present bool true Require @version tag
version.require_increment_on_change bool true Require version bump when body changes
exclude list [] Regex patterns for files to skip (applies to both validation and trace)
tags.req.cross_reference bool true Validate @req IDs exist in requirements file
version_gate.current_version string — auto:git, auto:cmake, or explicit version
version_gate.version_field string — Column in requirements file for version gating

trace section

Key Type Default Description
format string plantuml Diagram output format
participant_field string — Requirements file column for participant resolution
static_participants list [] Actors/entities always shown (e.g., {name: User, type: actor})
external list [] External participants (see below)
external_fallback string External Fallback name for unresolved sources (warns and omits in behavioral mode)

External participants

Route events to named external actors by prefix. Boundary functions produce protocol-labeled arrows via label_template. Entry chains prepend upstream participant arrows.

trace:
  external:
    - Cloud:
        receives_prefix: ["MQTT:"]
        boundary_functions: ["CloudMgr_Publish"]
        label_template: "MQTT: {arg0}"
        entry_chain:
          - { from: User, to: Mobile, label: "{req_name}" }
          - { from: Mobile, to: Cloud, label: "{req_name}" }
    - MCU:
        receives_prefix: ["DURABLE:"]
        boundary_functions: ["DurableEventCb"]
    - Hardware:
        receives_prefix: ["EVENT_HW_"]
Sub-key Purpose
receives_prefix Route @receives events matching these prefixes to this participant
boundary_functions Function names that cross this system boundary (for @calls edges)
label_template Format boundary call labels — {arg0}, {arg1} substituted from call args
entry_chain Upstream participant arrows prepended before entry edge

trace.options

Key Type Default Description
autonumber bool true Number sequence arrows
box_label string System Internal participant box label
box_color string #LightBlue Internal participant box color
min_edges int 1 Minimum behavioral edges to generate a diagram
show_returns bool false Show return arrows and activation bars on @calls edges
show_recovery_notes bool true Show callee names in empty catch blocks
max_condition_length int 80 Truncation limit for alt/loop conditions
infer_sends bool true Infer @sends from event post function calls
infer_calls bool true Infer @calls from cross-module calls
event_send_functions list [] Event post function names for generated code (escape hatch)
event_receive_functions list [] Registration function names for generated code (escape hatch)
legend bool false Render arrow style legend
label_mode string brief Label style: full (event+function), brief (event name only)

impact section

Key Type Default Description
requirements.file string — Path to requirements file
requirements.format string csv Format: csv, json, or yaml
requirements.id_column string Req ID Requirement ID column/field
requirements.name_column string Requirement Name Requirement name column/field

File-Level Doxygen

Each source file should have a file-level doxygen block. Use @participant to set the participant name for all functions in the file:

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

The requirements-file participant_field takes precedence over @participant for participant resolution. @participant is the fallback when no requirements mapping exists. Enable validate.presence.require_file_doxygen: true to enforce file-level blocks.

For Python:

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

Infrastructure Roots

Mark event bus functions once to enable automatic inference:

/**
 * @brief Post an event to all registered handlers.
 * @version 1.0
 * @req REQ-0050
 * @send_source
 */
void Event_post(uint64_t event, void *data) { ... }

/**
 * @brief Register a handler for events matching a bitmask.
 * @version 1.0
 * @req REQ-0050
 * @receive_source
 */
void Event_register(uint64_t mask, event_handler_fn handler) { ... }

With these in place, @sends and @receives are derived from the AST for all other functions — zero manual behavioral tags needed.

Generated Code

For code generators that rebuild files on every build (UDM, protobuf, HAL generators), annotations on generated files are destroyed. Use event_send_functions and event_receive_functions as config-level overrides:

trace:
  options:
    event_send_functions: ["dm_event_callback"]
    event_receive_functions: ["register_fsm_handler"]

These tell the tool to treat calls to these functions as send/registration points, equivalent to @send_source / @receive_source but without requiring tags on the generated source. Use this only for generated code you cannot annotate. For code you own, use @send_source / @receive_source tags instead.

Both default to empty lists — @send_source / @receive_source tags are the primary mechanism.

Config Validation

The config file is validated at load time against a built-in schema. Unknown keys are rejected with an error message:

doxygen-guard config error: Unknown key 'trace.optoins' — did you mean 'trace.options'?

trace.options values are type-checked after merge with defaults. Invalid types produce warnings:

WARNING: trace.options.min_edges must be int >= 0, got 'banana'

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"
  1. Add @participant to each file — one line per file sets the participant name for diagrams.

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

  3. Mark infrastructure roots — if you have an event bus or message dispatcher, add @send_source/@receive_source once to enable automatic inference.

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

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

Supported Languages

Language Extensions Comment Style Body Detection
C .c, .h /** ... */ Brace matching
C++ .cpp, .hpp, .cc, .cxx /** ... */ Brace matching
Java .java /** ... */ Brace matching
Python .py ## ... Indentation

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 trace --all src/
doxygen-guard trace --req REQ-001 src/
doxygen-guard impact --staged src/*.c
doxygen-guard coverage src/

# Verbose mode
doxygen-guard -v trace --all src/

License

MIT — see LICENSE.

Metadata

Release files for doxygen-guard 1.2.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for doxygen-guard 1.2.8
File Size Uploaded Provenance Actions
doxygen_guard-1.2.8.tar.gz 917.6 kB With provenance Details for doxygen_guard-1.2.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for doxygen-guard 1.2.8
File Interpreter ABI Platform Actions
doxygen_guard-1.2.8-py3-none-any.whl Python 3 none any Details for doxygen_guard-1.2.8-py3-none-any.whl

Total release size: 977.7 kB

Release files / doxygen_guard-1.2.8.tar.gz

Download URL doxygen_guard-1.2.8.tar.gz
Size 917.6 kB
Tags Source
SHA-256 checksum
How to use checksums
38e1d366f70e4ae4852c9b272b833a152bd3e777bc9178ce95e8ce7f979eb3f2
BLAKE2b-256 checksum
How to use checksums
65bbec19193776e51e5252005586b6688ea4e43bf3e9ebd546ff5edbce78ae75
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 22, 2026.

Transparency log

Release files / doxygen_guard-1.2.8-py3-none-any.whl

Download URL doxygen_guard-1.2.8-py3-none-any.whl
Size 60.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f20e788dc6d798612d59e82e00dc7f24c30b661c0f55eec668dae03dd5ab4c9a
BLAKE2b-256 checksum
How to use checksums
2477e6a9670e1b3ce240267ff4f644f6ac950e7e28daea7da9d969702823c5ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 22, 2026.

Transparency log

Security for doxygen-guard 1.2.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for doxygen_guard-1.2.8.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page