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 [] [] 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.    *

18.    *

© COPYRIGHT 2014  深圳电应普科技有限公司  

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

20.    */}

 

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

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

1.   /**     

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

3.    *     @{

4.    */ 

5.    

1. ... 定义的内容 ...

7.    

8.   /**

9.    *      @}// 模块结尾

10.   */

 

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

1.   /**     

2.    *    addtogroup  

3.    *     @{

4.    */ 

5.    

1. ... 定义的内容 ...

7.    

8.   /**

9.    *      @}

10.   */

 

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

1.   /**     

2.    *    @name 分组说明文字 

3.    *     @{

4.    */ 

5.    

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

7.    

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会为你生成左边树目录。

 

• Dot

如果你选用内置的生成功能（即选择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项自己保存。