Doxygen1.8.5+GraphViz2.34 构建源代码帮助文档

4 篇文章 0 订阅
2 篇文章 0 订阅

        因为项目需要,试着将Qt工程的所有源代码生成了html格式的帮助文档。下面是简要的方法说明。


Graphviz


        (英文:Graph Visualization Software的缩写)是一个由AT&T实验室启动的开源工具包,用于绘制DOT语言脚本描述的图形。它也提供了供其它软件使用的函式庫。Graphviz是一个自由软件,其授权为Eclipse Public License。


Doxygen


        Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,完全支持C、C++、Java、Objective-C和IDL语言,部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始,生成HTML格式的在线类浏览器,或离线的LATEX、RTF参考手册。


Doxygen配置


        运行Doxywizard,开始配置:

        单击Wizard选项卡,输入项目名,这个名字会作为文档的大标题,输入版本,也会出现在文档中,然后输入源代码的根目录,勾选”Scan recursively”,输入文档输出路径。在Working Directory中一般也输入源代码的根目录,主要是因为配置的一些选项中有的用相对路径,这个就可以作为相对路径的参照点。如图1所示:


        单击Diagrams标签,如果没安装GraphViz,则保持默认选择“Use built-in class diagram generator”。我这里已经安装了GraphViz2.34,将所有选项勾上。(注意这里仅是配置由GraphViz生产的东东,待会还要指定GraphViz的安装目录,否则Doxygen可不知道你的GraphViz在哪。。。。)


        单击Expert选项卡,会弹出一个有更多标签页的对话框:

        在"Project"标签页下,将OUTPUT_LANGUAGE设置为Chinese,因为我需要生成中文文档。勾选JAVADOC_AUTOBRIEF,即支持JavaDoc的语法,这样就可以用熟悉的JavaDoc风格的文档注释了。

        在" Input "标签页下,INPUT_ENCODING保持默认的utf-8,因为我的源代码文件的编码默认就是utf-8,你可以依据自己的指定相应的编码。FILE_PATTERNS下的后缀表明是需要扫描的代码文件,你可以只留下*.h、*.hpp、*.c、和*.cpp等,意思是只扫描C++头文件和源文件。下拉滚动条,会有EXCLUDE和EXCLUDE_PATTERNS表示不要进行解析的目录和文件,即工程目录下有的目录不需要进行文档化(比如.SVN配置目录),就用这两个排除掉。

        在"Source Browser"标签页下,勾选“SOURCE_BROUSER”,这样文档中就会附加一份源码,方便随时查阅。

        在"Dot"标签页下,DOT_PATH指定安装的GraphViz的bin目录所在位置,DOT_IMAGE_FORMAT可以指定GraphViz生成的图片格式,这里选择gif,如图所示:


        这个配置好的文件以后可以重复利用,每次点”Load…”装载进来,然后点击”Wizard…”,根据不同的工程,修改工程名字,版本,源代码根目录,文档输出目录就可以了,不用再重复上述配置。


源代码注释语法(JavaDoc)


        这里仅列出几条常用样例,详细语法请度娘之。。。

文件头注释

/** @file
 * @brief  模型结构类.
 * @author FCQ
 * @date June6,2012
 * @version 1.0.0.0
 * @note
 * 模型结构类的所有定义
 */

说明:    @file 独占一行,@file后我们空着,Doxygen会默认为是当前文件的文件名。

   @brief是有关该类的简要注释

   @note 后面另起一行是关于该文件的详细注释。(其本身独占一行)换行可用<br>

 

类注释

/**
* @class ClassBase class_base.h
* @brief 所有类的基类
* @author FCQ
* @date June6,2012
* @note
* 基类的定义 <br> 
* 所有类均从me派生 <br> 
* 这里定义了所有基本操作
*/

说明: @class 后面紧随当前类名和类所在的头文件名

             @brief是有关该类的简要注释

             @note后面另起一行是关于该类的详细注释。(其本身独占一行)换行可用<br>

函数注释

//! ClassBase 的构造函数 <br>
ClassBase(conststd::string&className,ClassBase *parent=0);

说明: //! 一行注释开头,换行可用<br>

             //!也可用来注释变量等,凡是只要其放在需要注释的(类、函数、变量、宏定义、枚举等)之前即可。

变量注释

int_id;                    ///< 每个实体的全局唯一ID

说明: 一行代码的后面放置注释必须采用 ///<的格式,切不可采用//!如果采用//!很肯能会导致Doxygen认为这是下一行的注释(因为它在下一行的紧邻前面)。


最终效果图








评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值