doxygen - SKILL.md Agent Skill

name: doxygen description: Inline documentation standard for the pool-controller C++ codebase using Doxygen. Use when asked to add, review, or fix inline code documentation. 🇩🇪 Deutsche Trigger: Inline-Dokumentation, Doxygen-Kommentare, Code-Dokumentation ergänzen, Quellcode dokumentieren.

Doxygen Documentation Standard

This project uses Doxygen (/** ... */) for all inline code documentation. PlatformIO/Arduino ecosystem standard — also used by ESP-IDF and most embedded C++ libraries.

Scope

Every header file (*.hpp) must have:
- A file comment with @file and @brief
- A class/struct comment with @brief
- Public method comments with @brief, @param, @return where applicable
Every source file (*.cpp) must have a file comment with @file and @brief
Private methods may have lighter comments; use a single-line /** ... */ for trivial getters/setters
Constants, macros, enums get a /** @brief ... */ comment

Style

File Header

/**
 * @file Config.hpp
 * @brief Pin assignments and compile-time constants for the Pool Controller.
 *
 * All GPIO pin assignments and tunable constants are centralized here.
 * Changing these values requires rebuilding the firmware.
 */

Class/Struct

/**
 * @brief Manages the pool pump relay state.
 *
 * Wraps an Arduino digital output pin as a relay switch.
 * Active-high logic: GPIO HIGH → relay ON.
 */
class RelayModuleNode final {

Public Method (full)

/**
 * @brief Attempts to parse a time string into hours and minutes.
 * @param timeStr  Input string in "HH:MM" format.
 * @param outHours Output parameter for parsed hours (0–23).
 * @param outMins  Output parameter for parsed minutes (0–59).
 * @return true if parsing succeeded, false on invalid format.
 * @note The input string must be at least 5 characters ("HH:MM").
 */
auto parseTime(const char* timeStr, uint8_t& outHours, uint8_t& outMins) -> bool;

Simple Getter/Setter (single line)

/** @brief Get current free heap in bytes. */
static auto getFreeHeap() -> uint32_t;

Free Function (namespace scope)

/**
 * @brief Check if enough time has elapsed since the last measurement.
 * @param lastMeasurement  Timestamp (ms) of the last measurement.
 * @param intervalSeconds  Desired interval in seconds.
 * @return true if intervalSeconds have elapsed since lastMeasurement.
 */
auto isMeasurementDue(uint32_t lastMeasurement, uint32_t intervalSeconds) -> bool;

Constants / Macros

/** @brief Interval for temperature sensor updates (seconds). */
static constexpr uint32_t TEMP_READ_INTERVAL{30};

/** @brief Default MQTT broker port. */
static constexpr uint16_t MQTT_DEFAULT_PORT{1883};

Tags Used

Tag	When to use
`@brief`	Required on every documented symbol — one-line summary
`@param`	Every function parameter, unless trivially obvious
`@return`	Every non-void return, unless trivially obvious
`@note`	Important caveats, edge cases, threadsafety
`@see`	Cross-reference to related functions/files
`@warning`	Dangerous behavior, side effects, 230V safety
`@file`	File header only — auto-populated from `\file`
`@author`	Optional — do NOT add; copyright already in file header

PlatformIO Integration

Generate HTML docs locally:

# Install doxygen
sudo apt install doxygen graphviz  # Debian/Ubuntu

# Generate (uses Doxyfile if present, otherwise default settings)
doxygen

# Output: docs/html/index.html

For CI, a Doxyfile can be added at the project root. Currently the docs are maintained for human readability in-IDE only (no CI Doxygen step).

Verification Checklist

Every *.hpp has a @file comment at the top
Every *.cpp has a @file comment at the top
Every class/struct has @brief
Every public method with parameters has @param for each param
Every non-void public method has @return
Single-line getters use /** @brief ... */ format
Trivial destructors, deleted constructors do NOT need doc comments