Doxygen安装使用

时间:2024-01-12 14:44:44

Doxygen是一个 C++CJavaObjective-CPythonIDLCORBA和Microsoft flavors)、FortranVHDLPHPC#D语言的文檔生成器。可以在大多数类Unix的系统上执行,以及Mac OS X操作系统和Microsoft Windows。初始版本的Doxygen使用了一些旧版本DOC++的源代码;随后,Doxygen源代码由Dimitri van Heesch重写。

Doxygen是一个编写软件参考文檔的工具。该文檔是直接写在源代码中,因此比较容易保持更新。Doxygen可以交叉引用文檔和源代码,使文件的读者可以很容易地引用实际的源代码。

KDE 使用Doxygen作为其部分文档且KDevelop具有内置的支持。 Doxygen的发布遵守GNU General Public License,并且是*软件

如同Javadoc,Doxygen提取文件从源文件的注解。除了Javadoc的语法,Doxygen支持Qt使用的文档标记,并可以输出成HTML、以及CHMRTFPDFLaTeXPostScript或man pages。

注释文档一般用两个星号标志:

/**
* <A short one line description>
*
* <Longer description>
* <May span multiple lines or paragraphs as needed>
*
* @param Description of method's or function's input parameter
* @param ...
* @return Description of the return value
*/

但也能和HeaderDoc一样使用*!的标志。 例如:

/*!
* <A short one line description>
*
* <Longer description>
* <May span multiple lines or paragraphs as needed>
*
* @param Description of method's or function's input parameter
* @param ...
* @return Description of the return value
*/

以下说明如何使C++的源文件产生文件。请确保参数EXTRACT_ALL在Doxyfile设置为YES。

/**
* @file
* @author John Doe <jdoe@example.com>
* @version 1.0
*
* @section LICENSE
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of
* the License, or(at your option)any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details at
* http://www.gnu.org/copyleft/gpl.html
*
* @section DESCRIPTION
*
* The time class represents a moment of time.
*/ class Time { public: /**
* Constructor that sets the time to a given value.
*
* @param timemillis Number of milliseconds
* passed since Jan 1, 1970.
*/
Time(int timemillis){
// the code
} /**
* Get the current time.
*
* @return A time object set to the current time.
*/
static Time now () {
// the code
}
};

另一种方法是首选的一些参数的记录如下。这将产生同样的文件。

       /**
* Constructor that sets the time to a given value.
*
*/
Time(int timemillis ///< Number of milliseconds passed since Jan 1, 1970.

{
// the code
}

安装配置:

Doxygen安装使用

说明:

Doxygen 工作目录(1:) 就是用来存放配置文件的目录,别无它用。

mode:

Wizard的Topics下的Mode,选择All Entities,可以输出相对完整的功能,是否包含源代码看你自身情况

Doxygen安装使用

选择 wizard 标签下的 Output Topics

相关配置说明如下图 2 所示。

Doxygen安装使用

选择 wizard 标签下的 Diagrams Topics

相关配置说明如下图 3 所示

Doxygen安装使用

选择 expert 标签下的 Project Topics

相关配置说明如下图 4 所示。

Doxygen安装使用

说明:编码格式,UTF-8 是首选。

选择 expert 标签下的 Input Topics

相关配置说明如下图 5 所示。

Doxygen安装使用

说明:

输入的源文件的编码,要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。

选择 expert 标签下的 HTML Topics

相关配置说明如下图 6 所示。

输出chm的问题:如何输出.chm文件
1. 你必须安装微软或其相兼容的chm编译系统。通常为HTML Help Workshop。

2. 首先在[Wizard]的Output页面中,选择HTML,然后选择到prepare for compressed HTML(.chm)。

3. 其次在[Expert]的HTML页面中,将HHC_LOCATION指向微软的hhc工具。通常为C:/Program Files/HTML Help Workshop/hhc.exe。然后点击OK,保存,编译即可。

Doxygen安装使用

图形问题:无法绘制类图协作图等图形。
首先确保安装了graphviz,注意不是wingraphviz,后者是一个graphviz的com封装,但是doxygen并不是基于它开发的,所以装了也没用。然后在 expert的Dot页DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。

如果出现无法包含.map文件的错误,可以将工作目录设置成html,并将html中所有文件都清除再试。这个问题的原因还不太确定。

生成文档

Doxygen安装使用

如何像MSDN那样在左边的树中显示函数列表?
打开[Expert]的HTML页面,然后选中TOC_EXPAND即可。

如何生成中文帮助?

点击[Expert],在页Project 的OUTPUT_LANGUAGE,选择Chinese,这样输出的帮助提示信息就是中文。具体中文提示信息的文字在源代码中。

如何修改或者去掉右下脚Generated at ...的文字?

打 开[Expert...]的HTML页面,然后在HTML_FOOTER中指定相应的HTML文件即可。注意HTML_FOOTER中至少包含BODY和 HTML结束标记。即一个最小的尾部HTML至少是这样</BODY></HTML>。同理,如果你要指定了 HTML_HEADER,他至少包含<HTML><HEAD></HEAD><BODY>

如何彻底解决DoxyGen的输出中文chm的乱码问题?
  DoxyGen的实现中大概有三处编码的设置。首先是,doxyfile,也就是配置文件。其次,INPUT_ENCODING,也就是DoxyGen需要解析的输入文件的编码。最后,就是输出的编码。譬如CHM左边的索引编码。

首先是chm的标题乱码,这个比较好解决,因为DoxyWizard使用QT做的界面,它内部做了转换,所以在DoxyWizard中输入中文,在保存的时 候,他自己做了转码,导致doxyfile中的最终的保存信息不正确。这个时候只需要用记事本打开doxyfile配置文件,输入相应中文即可。注意保存 的时候保存成ANSI编码即可。保存成其他格式的话可能需要去掉BOM,比较麻烦,没研究了。这个相应的编码设置在[Expert...]中,页 Project 的 DOXYFILE_ENCODING,不输入或者默认为UTF-8都行。

其次是右边内容乱码,这个多半是因为你没有配置好输入的文件编码类型造成的。在[Expert...]的Input页面中,有一个 INPUT_ENCODING,这个选项表示输入文件的编码方式,这要和你处理的源文件格式一致。对于我们来说(使用vs的人),一般设置为 GB2312。当然,再次声明,编码方式取决于源文件的编码方式。如果文件编码已经是UTF-8了,然而你还将其设置成GB2312,那么DoxyGen 会将UTF-8当成ANSI再进行一次UTF-8转换,自然会出错了。

最后也是经常遇到的问题就是DoxyGen生成的CHM文件的左边树目录的中文变成了乱码。这个只需要将chm索引的编码类型修改为GB2312即可。在 HTML的CHM_INDEX_ENCODING中输入GB2312即可。然而这种方法下,还有一个瑕疵之处,就是chm的搜索页的搜索结果中显示的中文 文字却变成乱码了。这是因为DoxyGen默认开启了HTML Help Workshop的Full-text search全文搜索选项,他在进行全文搜索的时候,应该是打开文件然后按照ANSI进行搜索的,(资料表示HHW不支持UTF-8,仅支持ISO- 8859-1或者windows-1252编码。)而Doxygen生成的右边界面统一是UTF-8,这自然出现了问题。而在这种情况下做全文搜索,理论 上只能搜索英文。

我们的解决方案只能是重新编译DoxyGen代码,为了满足搜索,只要保证右边的页面文件不是UTF-8即可。我们首先修改 writeDefaultHeaderFile这个函数的代码,将其charset=GB2312。然后在 TranslatorDecoder的构造函数中修改m_toUtf8 = (void*)-1;即屏蔽文本写入时最终的转换函数。最后删除INPUT_ENCODING的设置或者输入UTF-8。这样会使DoxyGen认为我们 的文本是UTF-8的,从而不用进行转换。生成替换原始的DoxyGen即可。

另外需要补充的是,还有一种方案是不用修改作者的源代码,但是需要将DoxyGen生成的右边的HTML文件使用工具(如iconv)手工转换成GB2312,然后再使用HTML Help Workshop生成,网上有篇文章介绍过,我测试一下,也是没有问题的。

主要参考:

http://blog.csdn.net/lostaway/article/details/6446786

http://blog.csdn.net/weiwangchao_/article/details/6831206

更多:

http://blog.sina.com.cn/s/blog_69e2b85e0101avq7.html

http://www.fmddlmyy.cn/text21.html

http://www.ibm.com/developerworks/cn/aix/library/au-learningdoxygen/

有用的设置

在expert->html->GENERATE TREEVIEW勾选

这会在添加一个侧边栏,并以树状结构显示包、类、接口等的关系。

在expert->source browser->勾选SOURCE BROWSER

这回把所有的源代码包含在其中