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

3、使用DoxyWizard生成CHM文档

安装好后，开始菜单会多出doxygen菜单，打开里面的DoxyWizard。界面如下图。

Step1是Doxygen的工作目录，请指定一个已存在的非中文的文件夹。

Step2做具体配置工作。

首先是Wizard选项卡：

Project

Project name: 项目名称

Project version or id: 项目版本号

Source code directory: 项目源码目录

Destination directory: 文档输出目录

Mode

保持默认选项（Document Entity Only与Optimize for C++ output）即可。

Output

要生成CHM文档请选择HTML项中的prepare for compressed HTML (.chm)。

同时将With search function (requires PHP enabled web server)的钩去掉。

LaTeX，如果不需要在文档中生成LaTeX公式的话可以不选。

Diagrams

选择第二项Use Build-In class diagram generator，将使用Doxygen内置的生成功能生成每个类的类图（如果它只有一个类的时候是不会生成的 = =）。

如果需要使用更强大的功能比如类继承体系图，请选择第三项Use dot tool from the GraphViz package，此功能需要安装GraphViz软件。

其次是Export选项卡，配置项比Wizard内容多出许多，这里只做简单介绍。

Project

OUTPUT_LANGUAGE，选择Chinese。

TAB_SIZE 是Tab的长度，默认为8，大家根据自己喜好……

Build

默认是会生成public方法，但是貌似有时会莫名奇妙地少掉一些方法的详细信息。

这里也选上EXTRACT_ALL，它保证输出所有public方法及protected方法，static方法不在此范围内。

若要包含static方法的注释，请选中EXTRACT_STATIC。

同理EXTRACT_PRIVATE。

我们生成文档的目的是为了方便各位调用类与函数，因此生成ALL、STATIC、LOCAL_CLASSES就好了吧 = =。

Messages

生成时的提示信息，默认即可。

Input

Input为输入目录，支持多个目录，我们可以放入项目目录和Include目录。

下面的Exclude是忽略目录与文件。

Source Browser

源码浏览器，默认即可。

Index

钩选ALPHABETICAL_INDEX，类中将有一个组合类型索引项。如下图所示：

HTML

如果你之前选择了prepare for compressed HTML (.chm)，

这里的GENERATE_HTMLHELP项会是钩选状态。

它下面的CHM_FILE填写你的CHM文档名字。

HHC_LOCATION则选择你的HTML Help WorkShop安装目录下的hhc程序，

一般会在C:/Program Files/HTML Help Workshop/hhc.exe。

Doxygen生成的默认是UTF-8，因此若不指定CHM_INDEX_ENCODING为GBK的话，CHM会有部分乱码。

钩选TOC_EXPAND，doxygen会为你生成左边树目录。

如果你选用内置的生成功能（即选择Use Build-In class diagram generator），此时CLASS_DIAGRAMS会是钩选状态，而HAVE_DOT则是未选状态，默认即可;

如果你选用GraphViz的dot工具生成（即选择Use dot tool from the GraphViz package）情况则相反，请你钩选上CLASS_DIAGRAMS。此时你需要设置下面的DOT_PATH为GraphViz的安装目录，否则将无法生成。

另外以下选项钩选则生成对应的图，不选则不生成：

CLASS_GRAPHS 类图
COLLABORATION_GRAPH 协作图
GROUP_GRAPHS 组图
UML_LOOK 是否UML外观
INCLUDE_GRAPH include
INCLUDED_BY_GRAPH 被include
CALL_GRAPH 调用
CALLER_GRAPH 被调用
DIRECTORY_GRAPH 目录图
GRAPHICAL_HIERARCHY 继承体系图

建议钩选以上下划线的几项。效果应如下所示：

DOT_IMAGE_FORMAT是生成的图片类型，有PNG/JPG/GIF三种格式可选。

其他项没有用过，请大家自己研究 = =。

配置好后即可运行，进入Run选项卡，单击Run doxygen即开始生成。

对话框会显示调试信息，生成好后点击下面的Show HTML Output可以打开生成的HTML首页。

chm文件则在你指定的生成目录中自己找。

关闭前不要忘了保存配置文件，下次可以继续使用。

它会自动提示你是否需要保存，你也可以选择File菜单的Save项自己保存。