A_OSWindowsVisual Studio
,
Source
Edit
History

【Visual Studio】Doxygen注释.md

文章目录
  1. 1. 0x01 文件头
  2. 2. 0x02 函数头
  3. 3. 0x03 类定义
  4. 4. 0x04 批注
  5. 5. 0x05 API 注释
  6. 6. 0x06 结构体注释
  7. 7. 0x07 版权声明

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

参考文章：

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

0x01 文件头

1
2
3
4
5
6
7
8
9
10
11
/**
 * @file 文件名
 * @brief 简介
 * @details 细节
 * @mainpage 工程概览
 * @author 作者
 * @email 邮箱
 * @version 版本号
 * @date 年-月-日
 * @license 版权
 */

0x02 函数头

1
2
3
4
5
6
7
8
9
10
11
12
13
/**
 * @brief 函数简介
 * @detail 详细说明
 * 
 * @param 形参 参数说明
 * @param 形参 参数说明
 * @return 返回说明
 *   @retval 返回值说明
 * @note 注解
 * @attention 注意
 * @warning 警告
 * @exception 异常
 */

0x03 类定义

1
2
3
4
/**
* @brief 类的简单概述
* 类的详细概述
*/

0x04 批注

1
2
3
4
5
6
7
8
/*!< ... 批注 ... */
/**< ... 批注 ... */ （推荐）
//!< ... 批注 ...
///< ... 批注 ...  （推荐）
    
Example:
using apollo::common::ErrorCode;              ///<错误码
using apollo::common::Status;                 ///<状态

0x05 API 注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/* 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 结构体注释

1
2
3
4
5
6
7
8
9
10
11
/**
 * @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 版权声明

1
2
3
/*****************************************************************************
 * Portfolio Info
 ****************************************************************************/