Skip to content

Isurwars/Correlation / .agents/skills/doc-generator

doc-generator

Verified

Audit 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 TagUsage RequirementExample
@briefRequired 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.
@returnRequired for non-void returning functions@return Computed RDF histogram.
@throwsRequired if function can throw exceptions@throws std::runtime_error On parse failure.

3. Audit Protocol

When asked to audit or document a file:

  1. Scan header file (.hpp) for public methods lacking /** blocks.
  2. Verify all parameters match @param tags.
  3. Verify return type matches @return tag.
  4. Ensure no inline NOLINT or suppression tags are inserted.
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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 467kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall