Sparkle Documentation Style Guide

Use this guide when writing Doxygen comments for every class and struct in Sparkle. The goal is to keep the generated API reference consistent, complete, and easy to navigate.

Class or struct blocks

Place the comment immediately above the declaration and start with @class or @struct.
Always add a short @brief that states the intent of the type.
For templates, add one @tparam per template parameter and spell out what the type represents, including constraints (what is accepted or excluded).
Add @see entries toward closely related types (helpers, factories, derived/base classes, alternative implementations).
Include a minimal C++ usage example so the reader can see how to construct/invoke the type.
Only document data members that are public; skip private/protected attributes.

template<typename FrameType>
class FrameQueue
{
public:
    size_t capacity() const noexcept;
};

Method blocks

Every method (including constructors and static functions) needs a comment.
Required tags: @brief, one @param per parameter, @tparam for template parameters, and @return when the function returns a value.
Use @see to point to overloads, complementary methods, or other types that produce/consume the same data.
For complex public methods, append a short usage example; keep internal/private examples minimal.
Keep the tone concise and action-oriented; prefer what the method does over how it does it.

bool push(FrameType frame);
std::optional<FrameType> pop();

Templates

Document every template parameter with @tparam, describing the intent and constraints (interfaces to satisfy, noexcept requirements, ownership rules, size limits, etc.).
If certain categories are disallowed (e.g., non-movable, reference types, raw pointers), call that out explicitly in the @tparam text.
For template methods, use @tparam alongside the method comment (not just on the class).

Cross references and examples

Use @see TypeName, @see TypeName::Method, or @see Namespace::Function to connect related APIs.
Keep examples minimal but runnable-looking; prefer construction + one key method call.
Wrap examples with @code{.cpp} / @endcode so Doxygen formats them as C++.

Quick checklist

Comment added above every class/struct with @class/@struct and @brief.

@tparam for every template parameter, with constraints.

@see for related types or methods.

Class-level usage example present.

Each method documented with @brief, @param(s), @tparam (if any), and @return (if it returns a value).

Examples only for complex public methods.

Only public data members are documented.