Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →Adds Doxygen-compatible documentation comments to C++ header files. Use this skill exclusively for adding or improving API documentation in existing header files (*.hpp, *.h). Do NOT create new resource files such as Doxyfile, scripts, or README files.
| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-04 | ✗→✓ | ▲ Improved | -10% | 0% |
| case-05 | ✗→✓ | ▲ Improved | -12% | 0% |
| case-06 | ✗→✓ | ▲ Improved | 34% | 0% |
| case-07 | ✗→✓ | ▲ Improved | 294% | 0% |
| case-08 | ✗→✓ | ▲ Improved | 113% | 0% |
Instructions for AI coding agents on adding Doxygen-compatible documentation comments to C++ header files.
> !NOTE] > This skill is for documenting header files only. Do NOT create new resource files (e.g., Doxyfile, scripts, README).
> Well-documented APIs enable developers to quickly understand and use components without reading implementation details.
> Documentation embedded in source code stays synchronized with implementation, reducing drift between code and documentation.
> Documentation comments serve as living specifications, keeping API contracts synchronized with implementation.
Effective API documentation follows these core principles.
> Document all public APIs including classes, functions, parameters, return values, and exceptions. Private implementation details may be omitted.
> Documentation provides context about usage patterns, performance characteristics, and thread safety guarantees.
> Use a uniform style, format, terminology and structure throughout the API documentation using the patterns defined in this skill.
> Use clear, brief descriptions. Avoid redundant information that restates what is obvious from the signature.
> Provide specific details about behavior, edge cases, and error conditions rather than vague statements.
> Documentation should be easy to access and navigate, integrated with development tools and workflows.
> Documentation must match the actual behavior. Update documentation whenever the implementation changes.
> Include usage examples, preconditions, postconditions, and error handling to help developers use the API correctly.
File-level documentation provides context for the entire header file.
> Describes the file's role in the project architecture.
> Identifies the original author(s) of the file.
> Specifies the licensing terms (typically SPDX identifier).
Namespace-level documentation describes the purpose of the namespace.
> A one-line summary of what the namespace contains.
> Extended description of the namespace's role and contents.
Class-level documentation describes the abstraction.
> A one-line summary of what the class represents.
> Extended description of responsibilities, invariants, and usage patterns.
> For template classes, document each template parameter's purpose and constraints.
Function-level documentation describes the contract.
> A one-line summary of what the function does.
> Document each parameter with @param including direction ([in], [out], [in,out]).
> Document the return value with @return or @retval for specific values.
> Document thrown exceptions with @throws or @exception.
> Use @warning for critical warnings about misuse.
> Use @note for important information.
> Document preconditions with @pre.
> Document postconditions with @post.
> Use @code and @endcode blocks for usage examples.
Cross-references link related documentation.
> Use @see to reference related functions, classes, or external resources.
Member-level documentation clarifies data semantics.
> Use ///< description for trailing inline documentation.
> Use /// description for preceding documentation.
Enumerations document possible values and their meanings.
> Document each enumerator with a brief Inline Comments description.
Organize related elements into logical groups.
> Use @defgroup to create named documentation modules.
> Use @ingroup to add elements to existing groups.
> Use @memberof for explicit class membership.
Class hierarchies and inherited documentation.
> Document inherited classes with @copydoc or @copybrief to reuse base class documentation.
Mathematical formulas using LaTeX syntax for algorithms and technical documentation.
> Use \f$..\f$ for formulas that appear within running text (opens LaTeX math mode).
> Use \f(...\f) for LaTeX elements that don't require explicit math mode (e.g., logos like \LaTeX).
> Use \f[...\f] for centered, unnumbered equations on separate lines.
> Use \f{environment}{...\f} for specific LaTeX environments (e.g., eqnarray*, align).
> Enable USE_MATHJAX in Doxyfile for client-side formula rendering without requiring LaTeX installation.
> Use FORMULA_MACROFILE configuration to define reusable LaTeX commands with \newcommand.
> !IMPORTANT] > Do NOT create Doxyfile, scripts, or other resource files. Only modify header files.
Identify undocumented or poorly documented public APIs in header files (e.g., src/<module>/<header>.hpp).
Add Doxygen-compatible documentation comments directly to header files following the templates below.
Include comprehensive documentation for:
Structure all documentation using the template patterns below.
Review documentation for accuracy and readability.
Doxygen supports multiple comment styles. Use the Javadoc style for consistency.
> Write documentation in clear, concise English. Use present tense for descriptions ("Returns the sum" not "Will return the sum").
> Keep documentation lines under 100 characters for readability.
> Use /** ... */ for multi-line documentation blocks. Each line within the block should start with * .
> Prefer /// for single-line documentation and /** */ for multi-line documentation blocks. Use Javadoc-style commands (@param, @return) rather than Qt-style (\param, \return).
> Use @brief for explicit brief descriptions.
> Add detailed descriptions after the brief, separated by a blank line or using @details.
> Always specify parameter direction using [in], [out], or [in,out] for clarity.
> Use @code and @endcode blocks for usage examples within documentation.
> Use @see to reference related functions, classes, or external resources.
> Use @note for important information and @warning for critical warnings.
> Mark deprecated APIs with @deprecated including migration guidance.
> Use @todo for planned improvements visible in generated documentation.
> Follow this order for function documentation: > 1. @brief > 2. @details (if needed) > 3. @tparam (for templates) > 4. @param > 5. @return > 6. @throws > 7. @pre > 8. @post > 9. @note > 10. @warning > 11. @see > 12. @deprecated
Use these templates for new documentation. Replace placeholders with actual values.
> !NOTE] > Place the @file block after the include guard (#pragma once or #ifndef/#define). This ensures the documentation is parsed once along with the declarations it describes and keeps preprocessor directives separate from API documentation.
cpp#pragma once /** * @file <filename>.hpp * @brief One-line description of the file's purpose. * * Detailed description of the file's contents and design decisions. * * @author <author_name> * @copyright Copyright (c) <year> <organization> * @license SPDX-License-Identifier: <license_identifier> */
cpp/** * @brief One-line description of namespace contents. * * Detailed description of the namespace's role, the types of * components it contains, and how they relate to each other. */ namespace namespace_name { // Namespace contents } // namespace namespace_name
cpp/** * @brief One-line description of the class. * * Detailed description of the class responsibility, key invariants, * and usage patterns. * * @tparam T Description of template parameter and constraints. * * @note Thread safety: Describe thread safety guarantees. * * @see RelatedClass * * @code * ClassName<int> obj; * obj.method(param); * @endcode */ template <typename T> class ClassName { // ... };
cpp/** * @brief One-line description of what the function does. * * Detailed description including algorithm details and edge cases. * * @param[in] param1 Description of the input parameter. * @param[out] param2 Description of the output parameter. * @param[in,out] param3 Description of bidirectional parameter. * * @return Description of the return value. * @retval specific_value Meaning of this specific return value. * * @throws std::invalid_argument If param1 is invalid. * @throws std::runtime_error If operation fails. * * @pre Preconditions that must be met before calling. * @post Postconditions guaranteed after successful execution. * * @note Important information for users. * @warning Critical warnings about potential misuse. * * @see relatedFunction() * * @code * auto result = functionName(input, output); * @endcode */ ReturnType functionName(const InputType& param1, OutputType& param2);
cppclass ClassName { private: int count_; ///< Number of items currently stored. bool is_valid_; ///< Whether the object is in a valid state. /// Description for simple members. int simple_member_; /** * @brief Buffer for temporary storage. * * Detailed explanation of the member's purpose and * synchronization requirements. */ std::vector<char> buffer_; };
cpp/** * @brief Description of what this enumeration represents. * * Detailed description of the enum's purpose and usage context. */ enum class EnumName { Success, ///< Operation completed successfully. Error, ///< Operation failed with an error. Pending, ///< Operation is still in progress. NotFound ///< Requested item was not found. };
cpp/** * @defgroup module_name Module Display Name * @brief One-line description of the module. * * Detailed description of the module purpose and components. * * @{ */ // Classes and functions belonging to this group /** @} */ // End of module_name
cpp/** * @brief Calculates the Euclidean distance between two points. * * The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is * \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$. * * For complex equations, use displayed formulas: * \f[ * d = \sqrt{\sum_{i=1}^{n}(p_i - q_i)^2} * \f] * * Multi-line equations using eqnarray environment: * \f{eqnarray*}{ * E &=& mc^2 \\ * F &=& ma * \f} * * @param[in] x1 X-coordinate of the first point. * @param[in] y1 Y-coordinate of the first point. * @param[in] x2 X-coordinate of the second point. * @param[in] y2 Y-coordinate of the second point. * * @return The Euclidean distance \f$d \geq 0\f$. */ double distance(double x1, double y1, double x2, double y2);
Other measured skills in the registry, with their headline benchmark lift.