60 lines
1.8 KiB
Plaintext
60 lines
1.8 KiB
Plaintext
---
|
|
description: C++ typing, style, file headers and mandatory doc blocks
|
|
globs: **/*.hpp, **/*.h, **/*.cpp
|
|
alwaysApply: false
|
|
---
|
|
|
|
# C++ typing, headers and documentation
|
|
|
|
Full spec: @AGENTS.md §2 and §3.
|
|
|
|
## Typing
|
|
- No primitive obsession: a frequency, a gain, a station id are their own
|
|
types, not int/float/uint8_t. Validate at construction.
|
|
- `enum class` always; never a bare enum. No bool for mode selection
|
|
(`setBand(Band::Dab)`, not `setBand(true)`).
|
|
- Parse untrusted input (network, UART, flash) once at the boundary into
|
|
a domain type; trust it downstream.
|
|
- `const` by default; `[[nodiscard]]` on status/value returns.
|
|
- Rule of zero: wrap every HW/OS handle in RAII. No raw new/delete.
|
|
- Borrow with `std::span`, never pointer+length.
|
|
- Command Query Separation. Functional core (pure, host-testable) /
|
|
imperative shell (all I2C/SPI/UART/flash). Core includes no ESP-IDF.
|
|
|
|
## File header (every .hpp/.cpp) — Apache-2.0
|
|
```cpp
|
|
/**
|
|
* @file <name>
|
|
* @brief <one line>
|
|
*
|
|
* DigiRadio firmware — https://github.com/manvalan/DigiRadio
|
|
*
|
|
* Copyright 2026 Michele Bigi
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*
|
|
* @author Michele Bigi
|
|
* @date <YYYY-MM-DD of creation>
|
|
*/
|
|
```
|
|
|
|
## Doc block — every class AND every method
|
|
Fields, in order, using Doxygen tags (aliases @dname/@pubstate defined
|
|
in Doxyfile):
|
|
```cpp
|
|
/**
|
|
* @brief <name> — one-line intent.
|
|
*
|
|
* @dname <name>
|
|
* @param <p> <meaning> // per parameter; none -> "none"
|
|
* @return <success + each error cause> // or void / n/a
|
|
* @pubstate <member state read/written; injected deps used; or none>
|
|
*
|
|
* Description: intent and contract, NOT a restatement of the code.
|
|
*
|
|
* @author Michele Bigi
|
|
* @date <YYYY-MM-DD>
|
|
*/
|
|
```
|
|
`doxygen Doxyfile` must exit 0 with an empty warnings log. Do not use
|
|
`EXTRACT_ALL = YES` to silence missing-doc warnings.
|