Isurwars/Correlation / .agents/skills/doc-generator
doc-generator
VerifiedAudit C++ headers for missing Doxygen documentation blocks, validate tag completeness (@param, @return, @throws), and format compliant block comments. Use when documenting APIs or auditing header comments.
Doxygen Documentation Generator
This skill enforces 100% Doxygen documentation compliance across all public/protected interfaces in C++ header files (.hpp, .h).
1. Compliance Standard
Every class, struct, enum, concept, and public/protected member function inside header files must declare a formatted Doxygen comment block.
Format Specification
Use block style /** ... */. Annotate parameter directions explicitly:
/**
* @brief Computes the pair distribution function g(r) from atomistic positions.
*
* Performs distance histogram binning over Cartesian particle coordinates
* using thread-local OpenMP reduction buffers.
*
* @param[in] coordinates Span of 3D Cartesian coordinates for all atoms in frame.
* @param[in] cutoff Maximum radial distance limit in Angstroms (must be > 0).
* @param[in] bin_width Radial bin resolution in Angstroms (must be > 0).
* @return Histogram profile containing bin centers and g(r) amplitudes.
* @throws std::invalid_argument If cutoff or bin_width is non-positive.
*/
[[nodiscard]] DistributionProfile compute_rdf(
std::span<const Vector3D> coordinates,
double cutoff,
double bin_width
);
2. Tag Reference Matrix
| Doxygen Tag | Usage Requirement | Example |
|---|---|---|
@brief | Required for all elements (1 sentence description) | @brief Manages trajectory file parsing. |
@param[in] | Input parameter (read-only) | @param[in] filename Path to input file. |
@param[out] | Output parameter (written by function) | @param[out] result Target output buffer. |
@param[in,out] | Modified parameter | @param[in,out] state Active calculator state. |
@return | Required for non-void returning functions | @return Computed RDF histogram. |
@throws | Required if function can throw exceptions | @throws std::runtime_error On parse failure. |
3. Audit Protocol
When asked to audit or document a file:
- Scan header file (
.hpp) for public methods lacking/**blocks. - Verify all parameters match
@paramtags. - Verify return type matches
@returntag. - Ensure no inline
NOLINTor suppression tags are inserted.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |