使用DOXYGEN风格注释

使用DOXYGEN风格注释

什么是DoxyGen ：这是一款可以根据约定好的注释，自动生成说明文档的软件（插件）。此软件（插件）完全免费。

为什么选择DoxyGen: 源代码编写者，仅需要简单的了解了DOXYGen的注释风格，既可以自动生成相应的代码注释文档，这有助于代码共享，同样的，也会对程序员形成一种规范的代码注释风格起到良好的影响。
 
Doxygen 支持 c 风格注释、 c++ 风格注释以及 javaDoc 风格注释等，下面将分别予以介绍。  

若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：

     1） 文件头（包括.h和.cpp）         

主要用于声明版权，描述本文件实现的功能，以及文件版本信息等

    2）类的定义

             主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述

    3）类的成员变量定义

             在类的成员变量上方，对该成员变量进行简要地描述

    4）类的成员函数定义

             在类定义的成员函数上方，对该成员函数功能进行简要描述

    5）函数的实现在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等    

常用的模板

/**

 *<A short one line description>

 *

 *<Longer description>

 *<May span multiple lines or paragraphs as needed>

 *

 *@param  <参数名> <参数说明>

 *@param  ...

 *@return <返回值说明>

 *@see    <相关函数>

 *@note   <注意>

 */

 

结构体描述模板

/**

 *<结构体简要说明>

 *

 *<结构体详细说明>

 */

 

文件描述模板

/**

 *@file

 *@author  <作者>

 *@date         <创建日期>

 *@version <版本号>

 *

 *@section LICENSE

 *

 *<文件说明>

 */

 @file 档案的批注说明。

@author 作者的信息 

@brief 用于class 或function的简易说明  
    eg：  @brief 本函数负责打印错误信息串

@param 主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明 

@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 本函数执行可能会产生超出范围的异常


使用自动生成器可以生成HTML格式的网页文件，程序员可以像浏览网页一样的查看文件说明，具体见下图。



 

图1.类、结构体列表。当前存在的结构体为tpyeerr

图2.类、结构体typeerr的成员列表，通过点击蓝色的名字可以自动链接到具体位置


 图3.文件视图:当前工程存在的文件只有main.c

 

 图4.打开main.c后，自动列出该文件包含所有内容，同样，点击蓝色的名称会自动链接到相应的地方去。