C语言编程规范--代码注释

1、什么是Doxygen?. 3

2、撰写正确格式的批注... 4

2.1常用指令介绍... 4

2.2简述与详述的方式... 6

2.3文件头注释... 6

2.4版权注释... 6

2.5模块定义（单独显示一页）... 7

2.6分组定义（在一页内分组显示）... 8

2.7变量、宏定义、类型定义简要说明... 8

2.8函数说明... 9

2.9枚举类型定义... 9

2.10项目符号标记... 10

3、使用DoxyWizard生成CHM文档... 11

1、什么是Doxygen?

Doxygen是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。

Doxygen就是在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文档了。

因此，Doxygen的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文档。

目前Doxygen可处理的程序语言包含：

C/C++
Java
IDL (Corba, Microsoft及KDE-DCOP类型)

而可产生出来的文档格式有：

HTML
XML
LaTeX
RTF
Unix Man Page

而其中还可衍生出不少其它格式。HTML可以打包成CHM格式，而LaTeX可以透过一些工具产生出PS或是PDF文档。

2、撰写正确格式的批注

若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：
    1）文件头（包括.h和.cpp）
        主要用于声明版权，描述本文件实现的功能，以及文件版本信息等
    2）类的定义
        主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述
    3）类的成员变量定义
        在类的成员变量上方，对该成员变量进行简要地描述
    4）类的成员函数定义
        在类定义的成员函数上方，对该成员函数功能进行简要描述
    5）函数的实现在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等

2.1常用指令介绍

可以在注释中加一些Doxygen支持的指令，主要作用是控制输出文档的排版格式，使用这些指令时需要在前面加上“\”或者“@”（JavaDoc风格）符号，告诉Doxygen这些是一些特殊的指令，通过加入这些指令以及配备相应的文字，可以生成更加丰富的文档，下面对比较常用的指令做一下简单介绍。

@file	档案的批注说明。 eg： @file stm32f10x_tim.c
@author	作者的信息 eg： @author MCD Application Team
@brief	用于class或function的批注中，后面为class或function的简易说明。 eg： @brief This file provides all the TIM firmware functions.
@param	主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明 eg： @param TIMx: where x can be 1, 2, 3, 4, 5 or 8 to select the TIM peripheral.
@return	描述该函数的返回值情况 eg: @return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
@retval	描述返回值类型，主要用于函式说明中，说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。 eg: @retval NULL 空字符串。 @retval !NULL 非空字符串。
@note	注解
@attention	注意
@warning	警告信息
@enum	引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg： @enum CTest::MyEnum
@var	引用了某个变量，Doxygen会在该枚举处产生一个链接 eg： @var CTest::m_FileKey
@class	引用某个类，格式：@class <name> [<header-file>] [<header-name>] eg: @class CTest "inc/class.h"
@exception	可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常
@todo	对将要做的事情进行注释
@see	一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。
@relates	通常用做把非成员函数的注释文档包含在类的说明文档中。
@since	通常用来说明从什么版本、时间写此部分代码
@deprecated
@pre	用来说明代码项的前提条件
@post	用来说明代码项之后的使用条件。
@code	在注释中开始说明一段代码，直到@endcode命令
@endcode	注释中代码段的结束。

2.2简述与详述的方式

在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是brief描述, 另一种就是detailed。两种都是可选的，但不能同时没有。

顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。

一般注释的描述由简述开始，经过特殊分隔方式后，后面紧跟详述的内容，javaDoc风格可以使用的分隔方法有以下两种：

1）使用@brief 参数标识，空行作为简述和详述的间隔标识

1. /** @brief Brief description.

2. * description continued.

3. *

4. * Detailed description starts here.

5. */

2）直接使用javaDoc风格，javaDoc风格自动以简述开头，以空行（或者小数点加空格）作为简述与详述的分割

1. /** Brief description

2. * description continued . (注意:这里有一个小数点,加上一个空格)

3. * Detailed description starts here.

4. */

2.3文件头注释

2.4版权注释

1. /**

2. ******************************************************************************

3. * @file stm32f10x_dma.c

4. * @author MCD Application Team

5. * @version V3.5.0

6. * @date 11-March-2011

7. * @brief This file provides all the DMA firmware functions.

8. ******************************************************************************

9. * @attention

10. *

11. * THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS

12. * WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE

13. * TIME. AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY

14. * DIRECT, INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING

15. * FROM THE CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE

16. * CODING INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS.

17. *

19. ******************************************************************************

20. */}

2.5模块定义（单独显示一页）

在文档注释块中使用'@defgroup'命令来定义一个组。命令有两个参数，第一个参数用来唯一标识组，第二个参数是指明该组在文档中显示的标题。

1. /**

2. * @defgroup 模块名模块的说明文字

3. * @{

4. */

... 定义的内容 ...

8. /**

9. * @}// 模块结尾

10. */

如果你使用同一个组名一次以上那么你会遇到一个错误。你可以使用'\addtogroup'来代替'\defgroup'来防止doxygen只限制唯一的标识。它的用法和'\defgroup'是一样的，不同的只是当多次使用一个组名的时候，它会自动将其中的内容和之前的组名合并。组的题目在这里是可选的，语法如下,

1. /**

2. * addtogroup <label>

3. * @{

4. */

... 定义的内容 ...

8. /**

9. * @}

10. */

2.6分组定义（在一页内分组显示）

1. /**

2. * @name 分组说明文字

3. * @{

4. */

6. ... 定义的内容 ...

8. /**

9. * @}// 模块结尾

10. */

2.7变量、宏定义、类型定义简要说明

由于Doxygen 对于批注是视为在解释后面的程序代码。也就是说，任何一个批注都是在说明其后的程序代码。如果要批注前面的程式码则需用下面格式的批注符号。

/*!< 成员变量描述 */

1）在成员变量上面加注释的格式

1. /** 成员变量描述 */

2. int m_Var;

2）在成员变量后面加注释的格式

1. int m_color; /*!< 颜色变量 */

1. /** @brief 简要说明文字（在前面加 @brief 是标准格式） */

2. #define MIN_UINT 0

1. /*

2. * 分行的简要说明 \n

3. * 这是第二行的简要说明

4. */

5. int b;

2.8函数说明

1. /*

2. * 简要的函数说明文字

3. * @param [in] param1 参数1说明

4. * @param [out] param2 参数2说明

5. * @return 返回值说明

6. */

7. int func(int param1, int param2);

1. /*

2. * 打开文件 \n

3. * 文件打开成功后，必须使用 ::CloseFile 函数关闭。

4. * @param[in] file_name 文件名字符串

5. * @param[in] file_mode 文件打开模式字符串，可以由以下几个模块组合而成：

6. * - r 读取

7. * - w 可写

8. * - a 添加

9. * - t 文本模式(不能与 b 联用)

10. * - b 二进制模式(不能与 t 联用)

11. * @return 返回文件编号

12. * - -1 表示打开文件失败

13.

14. * @note 文件打开成功后，必须使用 ::CloseFile 函数关闭

15. * @par 示例:

16. * @code

17. // 用文本只读方式打开文件

18. int f = OpenFile("d:\\test.txt", "rt");

19. * @endcode

20.

21. * @see ::ReadFile ::WriteFile ::CloseFile

22. * @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。

23. */

24. int OpenFile(const char* file_name, const char* file_mode);

2.9枚举类型定义

1. /** 枚举常量 */

2. typedef enum TDayOfWeek

3. {

4. SUN = 0, /*!< 星期天（注意，要以 “<” 小于号开头） */

5. MON = 1, /*!< 星期一 */

6. TUE = 2, /*!< 星期二 */

7. WED = 3, /*!< 星期三 */

8. THU = 4, /*!< 星期四 */

9. FRI = 5, /*!< 星期五 */

10. SAT = 6 /*!< 星期六 */

11. }

12. /** 定义类型 TEnumDayOfWeek */

13. TDayOfWeek TEnumDayOfWeek;

2.10项目符号标记

通过在每行的开头添加一系列列对齐的减号('-')，可以生成一个列表。列表项也可以具有标号，这需要在减号的后面跟上一个'#'。列表也可以是嵌套的，这取决于列表项的缩进方式。注意不要忘记'-#'后面的空格。

1. /*!

2. * A list of events:

3. * - mouse events

4. * -# mouse move event

5. * -# mouse click event\n

6. * More info about the click event.

7. * -# mouse double click event

8. * - keyboard events

9. * 1. key down event

10. * 2. key up event

11. *

12. * More text here.

13. */

The result will be:

A list of events:

mouse events
1. mouse move event
2. mouse click event
  More info about the click event.
3. mouse double click event
keyboard events
1. key down event
2. key up event