【Visual Studio】Doxygen注释.md

概述： Doxygen 注释及使用 C++版

参考文章：

• Doxygen Manual: Documenting the code
• Doxygen - 治好了我的代码注释强迫症 - 知乎
• Doxygen 注释语法和使用-CSDN博客

这里展示一些常用到的文件注释

0x01 文件头

/**
 * @file 文件名
 * @brief 简介
 * @details 细节
 * @mainpage 工程概览
 * @author 作者
 * @email 邮箱
 * @version 版本号
 * @date 年-月-日
 * @license 版权
 */

0x02 函数头

/**
 * @brief 函数简介
 * @detail 详细说明
 * 
 * @param 形参 参数说明
 * @param 形参 参数说明
 * @return 返回说明
 *   @retval 返回值说明
 * @note 注解
 * @attention 注意
 * @warning 警告
 * @exception 异常
 */

0x03 类定义

/**
* @brief 类的简单概述
* 类的详细概述
*/

0x04 批注

/*!< ... 批注 ... */
/**< ... 批注 ... */ （推荐）
//!< ... 批注 ...
///< ... 批注 ...  （推荐）
    
Example:
using apollo::common::ErrorCode;              ///<错误码
using apollo::common::Status;                 ///<状态

0x05 API 注释

/* GLOBAL FUNCTIONS */
/**
 * @brief Example showing how to document a function with Doxygen.
 *
 * Description of what the function does. This part may refer to the parameters
 * of the function, like @p param1 or @p param2. A word of code can also be
 * inserted like @c this which is equivalent to <tt>this</tt> and can be useful
 * to say that the function returns a @c void or an @c int. If you want to have
 * more than one word in typewriter font, then just use @<tt@>.
 * We can also include text verbatim,
 * when the language is not the one used in the current source file (but
 * <b>be careful</b> as this may be supported only by recent versions
 * of Doxygen). By the way, <b>this is how you write bold text</b> or,
 * if it is just one word, then you can just do @b this.
 *
 * @param [in] param1 Description of the first parameter of the function.
 * @param [out] param2 The second one, which follows @p param1, and represents output.
 *
 * @return Describe what the function returns.
 * @retval XXX_OK if successful.
 *
 * @see doxygen_theSecondFunction
 * @see Box_The_Last_One
 * @see <http://website/>
 * @note Something to note.
 * @warning Warning.
 */
int doxygen_theFirstFunction(int param1, int param2);

0x06 结构体注释

/**
 * @brief Use brief, otherwise the index won't have a brief explanation.
 *
 * Detailed explanation.
 */
typedef struct BoxStruct
{
    int a;    /**< Some documentation for the member BoxStruct#a. */
    int b;    /**< Some documentation for the member BoxStruct#b. */
    double c; /**< Etc. */
} tBoxStruct;

0x07 版权声明

/*****************************************************************************
 * Portfolio Info
 ****************************************************************************/