doxygen 注释规范_Doxygen代码注释规范.docx

Doxygen代码注释规范

基于Doxygen的代码注释规范一、Doxygen系列软件介绍1、DoxygenDoxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。Doxygen能将程序中的特定批注转换成为说明文件。它可以依据程序本身的结构，将程序中按规范注释的批注经过处理生成一个纯粹的参考手册，通过提取代码结构或借助自动生成的包含依赖图(includedependency graphs)、继承图(inheritance diagram)以及协作图(collaborationdiagram)来可视化文档之间的关系，Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML等。2、graphvizGraphviz(Graph Visualization Software)是一个由AT&T实验室启动的开源工具包,用于绘制DOT语言脚本描述的图形。要使用Doxygen生成依赖图、继承图以及协作图，必须先安装graphviz软件。3、HTML Help WorkShop微软出品的HTML Help WorkShop是制作CHM文件的最佳工具，它能将HTML文件编译生成CHM文档。Doxygen软件默认生成HTML文件或Latex文件，我们要通过HTML生成CHM文档，需要先安装HTML Help WorkShop软件，并在Doxygen中进行关联。二、软件下载与安装Doxygen下载(doxygen-1.8.7-setup.exe)：http://www.stack.nl/~dimitri/doxygen/download.htmlgraphviz(for windows)下载：/Download..phpHTML Help WorkShop(1.32)下载：/download/0/a/9/0a939ef6-e31c-430f-a3df-dfae7960d564/htmlhelp.exe软件安装都选择默认方式，点击下一步直至安装完成。安装完后进行Doxygen配置时需要关联graphviz和HTML Help WorkShop的安装路径。三、软件配置使用我们的所有配置都在Doxywizard中进行，生成参考手册是通过运行Doxywizard得到。(1)Wizard->Project最重要的是工作目录，源代码目录，生成参考文件目录三处的设定，其它项目名称、项目简介、版本和标识可以依照实际情况选填。工作目录是新建的一个目录，在配置完成之后可以把配置文件存在这个目录里，每次从这个目录中导入配置文件(.cfg)，然后进行说明文档生成。源代码目录和最终的结果目录在每一次运行Doxywizard时都进行设定。(2)Wizard->Mode 选择编程语言对应的最优化结果，按照编程语言选择。(3)Wizard->Output 选择输出格式，选HTML下的(.chm)项，为最后生成chm做准备。由于不需要LaTeX结果，不选此项。(4)Wizard->Diagrams 选择dot tool项，通过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中填入HTMLHELP WORKSHOP安装目录中hhc.exe的路径，将chm编码方式改为GBK方式，与第(6)步中的输入编码方式一致。(8)Expert->Dot 在Dot_PATH中填写GraphViz的安装路径。需要在build中配置EXTRACT_ALL和LOCAL_METHODS才能生成所有的变量和函数。(9)存储配置信息。到上一步Doxygen已经完全配置好，可以在Run中点击运行了，但为了保存以