用doxygen为C/C++程序自动生成文档（一），简介及安装

用doxygen为C/C++程序自动生成文档（一），简介及安装

2009-9-29 21:33:49 收藏 | 打印 | 投票(3) | 评论(0) |
阅读(51779) ◇字体：［大 中 小］
用doxygen为C/C++程序自动生成文档（一）
转载请注明：http://blog.mcuol.com/User/fenghua/Article/17348_1.htm

这几天有人问起关于文档生成工具的问题，个人觉得 doxygen 是一个不错的由C/C++ 注释自动生成文档的工具软件。在这里简单说明一下 doxygen 的使用，供大家参考。

一、doxygen 简介

二、简单说，doxygen 就是一个文档系统，它可以为C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D 等语言生成文档。

官方网站：http://www.stack.nl/~dimitri/doxygen/index.html

它可以从三个方面帮助我们：

1、 它可以产生HTML格式的在线文档或LATEX格式的离线参考手册，另外它还可以生成RTF（MS-WORD）, PostScript, 带超链接的PDF，压缩的HTML，unix man 等格式的文档。这些文档是直接从源文件提取的，这有助于保持代码和文档的一致性。

a) Doxygen在输出HTML文档时，自动生成用于制作CHM的项目文件（.hhp）、目录文件（.hhc）和索引文件（.hhk）。可以使用HTML Help Workshop中的CHM编译器（hhc.exe）编译后生成CHM文件。
b) Doxygen输出LATEX文档的同时，生成了了转换成pdf格式的文件的makefile。只要系统安装了相应的TEX工具，就可以从LATEX文档生成pdf文档。
c) Doxygen输出的RTF格式，针对Word作了优化，可以很好的转换到Word文档。
2、 通过配置 doxygen，可以从非文档化的源文件中提取源文件结构，这有助于帮我们理清大的源码包的结构。它能够自动的产生包括：依赖图，继承图，协作图等元素之间关系的图表（需要graphviz支持）。

a) Graphviz是一个图形化软件，Doxygen使用Graphviz生成各种图形。

b) Graphviz下载地址 http://www.graphviz.org/Download..php

3、 甚至可以“滥用”来创建普通文档。
http://www.graphviz.org/Download..php
三、Doxygen协议

Doxygen是在GPL协议下发布的，你可以使用其源码或编译好的二进制文件。Doxygen几乎可以在所有的linux兼容系统上运行，它也可以运行在windows环境。你可以根据需要选择。

四、 Doxygen的文档、FAQ、使用者和相关文章

a) http://www.stack.nl/~dimitri/doxygen/manual.html

b) http://www.stack.nl/~dimitri/doxygen/faq.html

c) http://www.stack.nl/~dimitri/doxygen/projects.html

d) http://www.stack.nl/~dimitri/doxygen/articles.html

五、使用Doxygen的一般步骤

a) 下载 Doxygen软件 http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc

b) 下载 Graphviz http://www.graphviz.org/Download..php

c) 安装 Doxygen 和 Graphviz（可选）

d) 准备一个配置文件（Doxyfile），通常用Doxywizard生成，然后可以根据需要修改（也可以不改）。

e) 按照Doxygen规则给源代码添加注释，将代码文档化

f) 运行Doxygen 产生和源代码对应的文档。

六、安装doxygen

a) Win下的安装

i. 直接运行Doxygen 的 Setup EXE文件，安装提示操作就可以了

ii. 运行Graphviz的安装（EXE）文件，按提示操作即可（可选）

b) 在unix兼容系统上采用编译源码方式安装 Doxygen

i. 采用源码安装 Doxygen 要确认你的系统安装有：

1. flex, bison 和 make等GNU工具

2. Perl

3. configure 脚步要求你的系统上有标准Unix命令如：sed, date, find, uname, mv, cp, cat, echo, tr, cd, and rm等

4. 为了使用Doxygen的高级功能，还需要安装以下附件工具

a) Qt3.3或更高版本，doxygen用其构建GUI前端doxywizard

b) 一个Latex软件：如teTeX 1.0，用来产生LaTex、Postscript和PDF格式的输出。

c) Graph visualization toolkit 1.8.10或更高版本。Doxygen用它生成包含图、依赖图、继承图和协作图等。如果采用编译源码方式安装graphviz，你的系统需要freetype支持。

d) 如果需要公式，或者你不希望使用pdflatex，则需要ghostscript，这个软件可以在www.ghostscript.com上找到

e) 为了产生Doxygen自己格式的文档，Python也是需要的，www.python.org.

ii. 解压下载的Doxygen源码包

1. tar xf doxygen-$VERSION.src.tar

2. ./configure 会根据系统自动配置doxygen，并产生相应的makefile

a) 可以configure --platform platform-type自定平台类型

b) configure --with-doxywizard 可以图形前端doxywizard

c) 更多信息可以通过configure –help查看，并给定相应的配置

iii. 编译Doxygen

1. make

iv. 可选的产生手册

1. make docs

2. make pdf

v. 安装 Doxygen

1. make install （需要root用户权限）

vi. 已知的问题

1. 有些系统中，QT头文件和库文件不在QTDIR环境变量指定的目录下，解决办法：

mkdir qt
cd qt
ln -s your-qt-include-dir-here include
ln -s your-qt-lib-dir-here lib
export QTDIR=$PWD
2. Bison 问题

a) Bison 1.31至1.34版本有一个Bug，可以使用1.35或1.31以前的版本

3. Latex问题

4. 文件 a4wide.sty 不是在所有的版本中都有效的，如果你使用的版本不支持请在config文件中选择其他的 pager type，具体可以参看 PAPER_TYPE 相关帮助

vii.

c) Ubuntu下采用二进制文件安装,可以用root用户使用下面的指令安装：

i. apt-get install doxygen doxygen-doc doxygen-gui graphivz

d) 其他安装细节请参考 http://www.stack.nl/~dimitri/doxygen/install.html

春节后在陆续整理使用和其他相关问题。