2.1. Standards: Doxygen: Crafting Excellent Documentation

Doxygen Governance Manual: Crafting Excellent Documentation

Introduction

Clear and well-structured documentation is essential for code maintainability, readability, and collaboration. Doxygen is a powerful tool that generates documentation from source code comments. This manual aims to establish best practices and guidelines for writing Doxygen comments that enhance the understanding and usability of your codebase.

Core Principles

• Clarity: Write comments that are easy to understand, even for developers who are not familiar with the specific codebase. Avoid jargon, ambiguity, and unnecessary technical details.
• Conciseness: Be brief and to the point. Avoid long, rambling sentences and paragraphs. Use clear, concise language to convey essential information.
• Consistency: Follow a consistent style and formatting throughout your Doxygen comments. This includes indentation, spacing, tag usage, and the level of detail provided.
• Completeness: Ensure your comments cover all the essential aspects of the code element being documented. Include information on the purpose, parameters, return values, possible errors, and any relevant side effects.
• Accuracy: Double-check your comments for technical correctness and ensure they accurately reflect the code's behavior and functionality.

Best Practices

• Use /**! */ for Single-Line Comments: This is the preferred format for brief descriptions, eliminating the need for the @brief tag:

/**! Retrieves the current Ethernet WAN interface name. */

• Use /** ... */ for Multi-Line Comments: For functions with parameters, return values, or more detailed explanations, use multi-line comments to maintain readability:

/**
 * @brief Initiates a firmware update and factory reset.
 * 
 * This function updates the device's firmware (optionally from a specified URL) 
 * and then performs a factory reset.
 *
 * ... (more details)
 */

• Focused @brief Tags: Keep the @brief description concise and action-oriented, summarizing the core purpose of the function or data structure.

• Informative @param and @returns:

  • @param: Clearly state the parameter's purpose, expected type, and any constraints or valid values. Use - to separate the parameter name from its description.
  • @returns: Provide a general overview of the return value and its meaning.

• Detailed @retvals: List each possible return value, followed by a hyphen and a clear explanation.

• Use Additional Tags: Leverage other Doxygen tags like @note, @warning, @see, and @deprecated to provide supplementary information, warnings, references, or deprecation notices.

• Error Handling (TODO): Prioritize moving away from generic RETURN_ERR values. Instead, define and use an enum for specific error codes to enhance debugging and clarity.

Example: Well-Documented Function

/**!
 * @brief Retrieves the current DOCSIS registration status.
 *
 * This function populates a provided `CMMGMT_CM_DOCSIS_INFO` structure with DOCSIS registration details. 
 *
 * @param[out] pinfo - Pointer to a pre-allocated `CMMGMT_CM_DOCSIS_INFO` structure.
 *
 * @returns Status of the operation:
 * @retval RETURN_OK - On success.
 * @retval RETURN_ERR - On failure (e.g., retrieval error, invalid input).
 *
 * @note The caller is responsible for providing the `PCMMGMT_CM_DOCSIS_INFO` structure.
 */
INT docsis_GetDOCSISInfo(PCMMGMT_CM_DOCSIS_INFO pinfo);

Common Pitfalls to Avoid

• Repetition: Avoid repeating information that is already clear from the code element's name or type.
• Vague Language: Be as specific as possible in your descriptions.
• Incorrect Information: Double-check your comments for technical accuracy.
• Overly Long Comments: Keep comments concise and focused on the most important details.