搜索
基于Doxygen的代码注释规范一、Doxygen系列软件介绍1、DoxygenDoxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。Doxygen能将程序中的特定批注转换成为说明文件。它可以依据程序本身的结构，将程序中按规范注释的批注经过处理生成一个纯粹的参考手册，通过提取代码结构或借助自动生成的包含依赖图（includedependencygraphs）、继承图（inheritancediagram）以及协作图（collaborationdiagram）来可视化文档之间的关系，Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML等。2、graphvizGraphviz(GraphVisualizationSoftware)是一个由AT&T实验室启动的开源工具包,用于绘制DOT语言脚本描述的图形。要使用Doxygen生成依赖图、继承图以及协作图，必须先安装graphviz软件。3、HTMLHelpWorkShop微软出品的HTMLHelpWorkShop是制作CHM文件的最佳工具，它能将HTML文件编译生成CHM文档。Doxygen软件默认生成HTML文件或Latex文件，我们要通过HTML生成CHM文档，需要先安装HTMLHelpWorkShop软件，并在Doxygen中进行关联。二、软件下载与安装Doxygen下载（doxygen-1.8.7-setup.exe）：~dimitri/doxygen/download.htmlgraphviz（forwindows）下载：（1.32）下载：软件安装都选择默认方式，点击下一步直至安装完成。安装完后进行Doxygen配置时需要关联graphviz和HTMLHelpWorkShop的安装路径。三、软件配置使用我们的所有配置都在Doxywizard中进行，生成参考手册是通过运行Doxywizard得到。（1）Wizard-Project最重要的是工作目录，源代码目录，生成参考文件目录三处的设定，其它项目名称、项目简介、版本和标识可以依照实际情况选填。工作目录是新建的一个目录，在配置完成之后可以把配置文件存在这个目录里，每次从这个目录中导入配置文件（.cfg），然后进行说明文档生成。源代码目录和最终的结果目录在每一次运行Doxywizard时都进行设定。（2）Wizard-Mode选择编程语言对应的最优化结果，按照编程语言选择。（3）Wizard-Output选择输出格式，选HTML下的（.chm）项，为最后生成chm做准备。由于不需要LaTeX结果，不选此项。（4）Wizard-Diagrams选择dottool项，通过GraphViz来作图。（5）Expert-Project选择输出目录，选着输出语言。如果代码中采用了中文注释，此处选择为中文。向下拉滑条，看见有JAVADOC_AUTOBRIEF和QT_AUTOBRIEF两个框，如果勾选了，在这两种风格下默认第一行为简单说明，以第一个句号为分隔；如果不选，则需要按照Doxygen的指令@brief来进行标准注释。（6）Expert-Input将输入编码方式改为GBK方式，确保输出中不会由于UTF-8方式导致乱码。最后也是经常遇到的问题就是DoxyGen生成的CHM文件的左边树目录的中文变成了乱码。这个只需要将chm索引的编码类型修改为GB2312即可。在HTML的CHM_INDEX_ENCODING中输入GB2312即可。（7）Expert-HTML勾选生成HTMLHELP项，输入生成CHM名称，在HHC_LOCATION中填入HTMLHELPWORKSHOP安装目录中hhc.exe的路径，将chm编码方式改为GBK方式，与第（6）步中的输入编码方式一致。（8）Expert-Dot在Dot_PATH中填写GraphViz的安装路径。需要在build中配置EXTRACT_ALL和LOCAL_METHODS才能生成所有的变量和函数。（9）存储配置信息。到上一步Doxygen已经完全配置好，可以在Run中点击运行了，但为了保存以上配置信息，可以将配置好的文件存一个.cfg文件，之后再运行Doxygen时只需要将该文件用Doxygen打开，改变第（1）步中的输入、输出目录及工程的信息再运行。File-Saveas,取一个名，默认为Doxyfile，加.cfg,点击保存。如果需要改变配置文件，改动之后再Save替换之前的配置文件即可。（10）Run-RunDoxygen即可运行Doxygen，运行完成后在输出目录中的html文件夹中找到index.chm文件即为输入代码的文档说明。四、Doxygen注释规范简介1、Doxygen规范综述简要的说，Doxygen注释块其实就是在C、C++注释块的基础添加一些额外标识,使Doxygen把它识别出来,并将它组织到生成的文档中去。在每个代码项中都可以有两类描述：一种就是brief描述,另一种就是detailed。两种都是可选的，但不能同时没有。简述(brief)就是在一行内简述地描述。而详细描述(detailed)则提供更长,更详细的文档。在Doxygen中,主要通过以下方法将注释块标识成详细(detailed)描述:JavaDoc风格，在C风格注释块开始使用两个星号'*'：/***...描述...*/Qt风格代码注释,即在C风格注释块开始处添加一个叹号'!':/*!*...描述...*/使用连续两个以上C++注释行所组成的注释块,而每个注释行开始处要多写一个斜杠或写一个叹号：//////...描述...///同样的，简要说明（brief）有也有多种方式标识，这里推荐使用@brief命令强制说明，例如：/***@brief简要注释BriefDescription.*/或者//////@brief简要注释BriefDescription.///需要注意以下几点：（1）Doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、全局变量、宏等注释，而忽略函数内局部变量、代码等的注释。（2）注释应写在对应的函数或变量前面。JavaDoc风格下，自动会把第一个句号.前的文本作为简要注释，后面的为详细注释。你也可以用空行把简要注释和详细注释分开。注意要设置JAVADOC_AUTOBRIEF或者QT_AUTOBRIEF设为YES。（3）先从文件开始注释，然后是所在文件的全局函数、结构体、枚举变量、命名空间→命名空间中的类→成员函数和成员变量。（4）Doxygen无法为DLL中定义的类导出文档例如：class__declspec(dllexport)CClassName:publicCObject{}所生成的文档中发现Doxygen无法识别出DLL中定义的类。2、Doxygen常用指令如前面所述的@brief命令，还可以在注释中加入其他Doxygen支持的指令，控制输出文档的排版格式，使用这些指令时需要在前面加上“\”或者“@”（JavaDoc风格）符号，告诉Doxygen这些是一些特殊的指令，通过加入这些指令以及配备相应的文字，可以生成更加丰富的文档下表列出常用的Doxygen指令：@file档案的批注说明。@author作者的信息@brief用于class或function的简易说明eg：@brief本函数负责打印错误信息串@param主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明@return描述该函数的返回值情况eg:@return本函数返回执行结果，若成功则返回TRUE，否则返回FLASE@retval描述返回值类型eg:@retvalNULL空字符串。@retval!NULL非空字符串。@note注解@attention注意@warning警告信息@enum引用了某个枚举，Doxygen会在该枚举处产生一个链接eg：@enumCTest::MyEnum@var引用了某个变量，Doxygen会在该枚举处产生一个链接eg：@varCTest::m_FileKey@class引用某个类，格式：@classname[header-file][header-name]eg:@classCTestinc/class.h@exception可能产生的异常描述eg:@exception本函数执行可能会产生超出范围的异常Modules（模块）：Modules是一种归组things在分离的page上的方式。组的成员可以是file，namespace，classes，functions，variables，enums，typedefs和defines，但也可以是其他groups。要定义一个group，应该在一个特殊注释块放置\defgroup。命令的第一个参数应该是唯一标志该group的标签。要将一个entity归为某个group的一个member，在entity前放置\ingroup命令。第二个参数是group的title。要避免在注释中每个member前放置\ingroup命令，可以将member用@{和@}封装起来。@{@}标记可以放置group的注释中，也可以在一个独立的注释块使用这些group的标记符号groups也可以嵌套。如果多次使用一个group标签，将会出错。如果不希望doxygen强行执行唯一标签，可以使用\addtogroup而非\defgroup。运作方式和\defgroup很像，但是如果该group已经定义，它默认向已存在的注释中添加一个新的项。Group的title对此命令是可选的，也可以考虑使用它。/**@defgroup模块名模块的说明文字*@{*/...定义的内容.../**@}*///模块结尾这样可以在其他地方以更加详细的说明添加members到一个group。注意compoundentities（例如classes，files和namespaces）可以放在多个groups中，但是members（例如variables，functions，typedefs和enmus）只可以归于一个groupMemberGroups如果一个compound（例如一个class或file）有多个members，通常我们希望将其group。Doxygen已经可以自动按照类型和protection级别将这些things归组在一起，但可能你会认为仅仅这样是不够的或者这种缺省的方法是错误的。例如你认为有不同（语法）的类型需要归入同一个group（语意）。这样定义一个membergroup：//@{...//@}块或者使用/*@{*/.../*@}*/3、Doxygen注释实例下述实例均以JavaDoc风格进行注释，在日常规范中也推荐尽量使用JavaDoc风格的注释。（1）文件注释文件不在任何东西里面，所以不能像类、函数等在上方放注释，只能用@file方式定义，其格式如下：/**@file[file‐name]*@briefbriefdescription*@authorlistofauthors*[@authorauthorsdescription]*@datedate*@versionversionnumber*@note*detaileddescr