TheRock/rocm-libraries/projects/hipdnn/docs/doxygen-guidelines.md

Doxygen Documentation Guidelines

Public API Scope

The following directories contain public API that requires Doxygen documentation:

Directory	Scope	Notes
backend/include/	All .h files	C API headers (hipdnn_backend.h, enums, status codes)
frontend/include/hipdnn_frontend/	All .hpp files except detail/ subdirectory	Frontend classes, attributes, error handling
frontend/include/hipdnn_frontend/attributes/	All attribute classes	Operation configuration (convolution, batchnorm, matmul, pointwise)
frontend/include/hipdnn_frontend/knob/	Knob system	Engine configuration knobs
plugin_sdk/include/	Plugin interfaces	For plugin developers

What to Exclude

• **/detail/** subdirectories - internal implementation
• **/src/** directories - private implementation files
• Test files (**/tests/**)
• Generated files (*_generated.h, *_generated.hpp)

Required Documentation Elements

File-level (all public headers):

/**
 * @file FileName.hpp
 * @brief One-line description of the file's purpose
 *
 * Optional longer description of what the file contains and when to use it.
 */

Class-level:

/**
 * @class ClassName
 * @brief One-line description
 *
 * Detailed description of the class purpose and usage.
 *
 * @code{.cpp}
 * // Example usage
 * ClassName obj;
 * obj.doSomething();
 * @endcode
 *
 * @see RelatedClass, relatedFunction()
 */

Function/Method-level:

/**
 * @brief Brief description of what the function does
 * @param paramName Description of the parameter
 * @return Description of return value
 * @throws ExceptionType When this is thrown
 * @see relatedFunction()
 */

Enum values:

enum class MyEnum
{
    VALUE_A,  ///< Description of VALUE_A
    VALUE_B,  ///< Description of VALUE_B
    VALUE_C   ///< Description of VALUE_C
};

Graph Operation Methods

Graph.hpp is the primary entry point for users. Operation methods (e.g., conv_fprop, matmul, pointwise, batchnorm) should include:

1. A @brief one-liner
2. A short formula showing the mathematical operation (use @code blocks)
3. @param tags documenting each input tensor with its expected shape
4. @return documenting each output tensor with its shape
5. A @see reference to the corresponding attributes class

/** @brief Convolution forward pass
 *
 * For 2D with NCHW layout:
 * @code
 * y[n,k,oh,ow] = sum_c,r,s  x[n, c, oh*stride+r*dilation-pad, ...]  *  w[k,c,r,s]
 * @endcode
 *
 * @param x Input activation tensor [N, C, H, W]
 * @param w Filter/weight tensor [K, C, R, S]
 * @param attributes Convolution parameters: padding, stride, dilation
 * @return y: Output activation tensor [N, K, OH, OW]
 *
 * @see ConvFpropAttributes
 */

When adding a new operation to Graph.hpp, add a Doxygen comment following this pattern before the method declaration.

Doxygen Comment Style

• Use /** ... */ for multi-line Doxygen comments
• Use ///< for inline enum/member documentation
• Never use /* */ inside Doxygen blocks - this causes nested comment warnings
• Use @code{.cpp} ... @endcode for code examples

When Adding New Public API

1. Add file-level @file and @brief documentation
2. Document all public classes with @class, @brief, and usage example
3. Document all public methods with @brief, @param, @return
4. Document all enum values with ///< inline comments
5. Run doxygen Doxyfile to verify documentation builds without warnings