API Documentation Status

Table of Contents

• 2. Warning Log and Build Path
• 3. Expected Standard For New APIs

This page describes current API-doc quality, warning sources, and the expected standard for new changes.

2. Implementation Status Matrix

API documentation quality is improving but not yet uniformly clean across all modules. Known issues in some headers/source pairs include:

• stale parameter names in Doxygen blocks,
• duplicate/missing @param entries,
• partial function-level docs on legacy-heavy paths.

Treat these as active maintenance items rather than hidden debt.

2. Warning Log and Build Path

Doxygen warnings are written to:

• logs/doxygen.warnings

Configured in docs/Doxyfile via:

• WARN_LOGFILE = ../logs/doxygen.warnings

CI currently enforces Markdown-link integrity; Doxygen warning cleanup remains a repository maintenance objective.

3. Expected Standard For New APIs

For newly added or modified public functions:

1. each parameter must have exactly one matching @param,
2. function summary should describe behavior and side effects,
3. return/CHKERRQ semantics should be documented,
4. cross-module dependencies should be explicit when non-obvious.

Minimum acceptable quality is interface correctness and discoverability, even when deep theoretical derivation is documented elsewhere.

1. Standard Extension Workflow

1. run docs build (make build-docs) where available,
2. inspect logs/doxygen.warnings,
3. patch one module at a time (include/*.h + matching src/*.c),
4. re-run warning pass and track net reduction.

Batching by module avoids regressions and keeps review scope manageable.

1. Reference Scales

• Code Architecture
• Maintenance Backlog and Low-Priority Fixes
• Testing, Smoke, and Quality Gates Guide