.clinerules - chunhualiao/public-docs GitHub Wiki

.clinerules for cpp projects

Documentation of C/C++ Source Files using Oxygen-Style

Generate precise, professional, Doxygen-compatible C++ function comments that make intent, contracts, and edge cases unambiguous—without repeating the obvious. What to Include:

  • Purpose and observable effects, not implementation details.

  • Inputs/outputs, ownership/lifetime, allocator behavior.

  • Error modes (return codes/exceptions), sentinel values.

  • Concurrency constraints, reentrancy, global/static state touched.

  • Performance characteristics, potential blocking/IO.

  • Stability guarantees (strong/weak exception safety).

  • Preconditions/postconditions/invariants.

What to exclude:

  • Obvious restatements of the signature (“Takes an int and returns bool”).

  • Line-by-line algorithm narration; put that in code comments if needed.

  • TODOs or speculative notes.

Formatting Templates

/**

* @brief <imperative one-line summary>

* @details <what it does and why it exists; context and guarantees>

* @tparam T <constraints/expectations>                        // if templated

* @param[in]  foo <units, range, ownership, nullability>

* @param[out] bar <what is written; post-state>

* @param[in,out] baz <how it is mutated; invariants>

* @return <meaning, units, sentinel semantics>

* @throws <Type> <condition>; ... or @throws None

* @pre <required state/ordering>

* @post <guaranteed state/outputs>

* @complexity <e.g., O(n log n) time, O(1) space; notes>

* @thread_safety <MT-Safe/Unsafe; locking/usage rules>

* @warning <gotchas/UB triggers>

* @note <additional notes: encoding, stability, perf quirks>

*/
⚠️ **GitHub.com Fallback** ⚠️