为什么选择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后,自动列出该文件包含所有内容,同样,点击蓝色的名称会自动链接到相应的地方去。