这几天有人问起关于文档生成工具的问题，个人觉得 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 等语言生成文档。
官方网站：
它可以从三个方面帮助我们：
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下载地址
3、 甚至可以“滥用”来创建普通文档。
三、Doxygen协议
Doxygen是在GPL协议下发布的，你可以使用其源码或编译好的二进制文件。Doxygen几乎可以在所有的linux兼容系统上运行，它也可以运行在windows环境。你可以根据需要选择。
四、 Doxygen的文档、FAQ、使用者和相关文章
a)
b)
c)
d)
五、使用Doxygen的一般步骤
a) 下载 Doxygen软件
b) 下载 Graphviz
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) 3.3或更高版本，doxygen用其构建GUI前端doxywizard
b) 一个Latex软件：如，用来产生LaTex、Postscript和PDF格式的输出。
c) 1.8.10或更高版本。Doxygen用它生成包含图、依赖图、继承图和协作图等。如果采用编译源码方式安装graphviz，你的系统需要freetype支持。
d) 如果需要公式，或者你不希望使用pdflatex，则需要ghostscript，这个软件可以在 上找到
e) 为了产生Doxygen自己格式的文档，Python也是需要的，.
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) 其他安装细节请参考
春节后在陆续整理使用和其他相关问题。
doxygen为C/C++程序自动生成文档之文档化代码（doxygen风格注释简介）
转载请注明：嵌入式学习网:
如果打算使用doxygen为代码产生文档，在编写代码时首先要为代码添加doxygen风格的注释，这些doxygen风格的注释可以称为文档块，添加注释的这个动作可以称为文档化代码。Doxygen会根据相应的doxygen注释块为代码生成相应的文档。
对每个代码条目，doxygen有两种（在某些情况下可以3种）类型的说明，共同组成文档：简要说明和详细说明，对应方法和函数可以有第三种风格的注释，函数体内注释。
简要说明只有一行长，详细说明可以有多行。
注释风格
详细注释可以有如下风格
1、JavaDoc风格的注释，这种风格的注释是在C风格的注释块开始处有两个 “ * “，如下：
/**
* ... 注释块 ...
*/
2、可以采用QT风格的注释，这种风格的注释是在C风格的注释块开始处“ * “后面紧跟”!”，如下：
/*!
* ... 注释块 ...
*/
以上两个例子中 text前的 “ * “ 是可选的，可以写成
/**
... 注释块 ...
*/
和
/*!
... 注释 ...
*/
3、单行注释也可以采用如下方式
///
/// ... 注释 ...
///
或
//!
//!... 注释 ...
//!
4、如下注释也是可以的
/********************************************//**
* ... 注释
***********************************************/
或者
/////////////////////////////////////////////////
/// ...注释...
/////////////////////////////////////////////////
简要说明有如下格式
1、 使用/brief 命令指定简要说明，简要说明以”.” 结束，详细说明在接下来的一个空行后开始，如下：
/*! /brief 简要说明.
* 简要说明续.
*
* 详细说明（上面要留一个空行）.
*/
如果配置文件中把 JAVADOC_AUTOBRIEF 设置成 YES，则可以使用JavaDoc风格注释块, 这种风格的注释，简要说明自动从“*“后开始 ，直到第一个”.”号结束，例如：
/** 简要说明.
* 详细说明.
*/
多行C++风格注释：
/// 简要说明.
/// 详细说明.
3、可以采用如下注释：
/// 简要说明.
/** 详细说明. */
或者
//! 简要说明.
//! 详细 （上面的空行是需要的）
//! 说明.
上例中间空行用来分隔简要说明和详细说明的。请注意下面格式的注释是不合法的，doxygen只允许一条详细说明对应一条简要说明：
//!简洁描述信息
//! 详细描述信息
/*! 注意，又一详细描述信息!
*/
如果一个代码项的声明和定义之前都有简要说明，则doxygen只使用声明之前的说明。
如果一个代码项在声明和定义之前都有详细说明, 则doxygen使用定义之前的说明。
用QT风格注释的C++代码样例
//! A test class.
/*!
A more elaborate class description.
*/
class Test
{
public:
//! An enum.
/*! More detailed enum description. */
enum TEnum {
TVal1, /*!< Enum value TVal1. */
TVal2, /*!< Enum value TVal2. */
TVal3 /*!< Enum value TVal3. */
}
//! Enum pointer.
/*! Details. */
*enumPtr,//! Enum variable.
/*! Details. */
enumVar; //! A constructor.
/*!
A more elaborate description of the constructor.
*/
Test();
//! A destructor.
/*!
A more elaborate description of the destructor.
*/
~Test();
//! A normal member taking two arguments and returning an integer value.
/*!
/param a an integer argument.
/param s a constant character pointer.
/return The test results
/sa Test(), ~Test(), testMeToo() and publicVar()
*/
int testMe(int a,const char *s);
//! A pure virtual member.
/*!
/sa testMe()
/param c1 the first argument.
/param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
//! A public variable.
/*!
Details.
*/
int publicVar;
//! A function variable.
/*!
Details.
*/
int (*handler)(int a,int b);
};
如果配置文件中JAVADOC_AUTOBRIEF 设置成 YES，可以使用JavaDoc风格注释
/**
* A test class. A more elaborate class description.
*/
class Test
{
public:
/**
* An enum.
* More detailed enum description.
*/
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar; /**< enum variable. Details. */
/**
* A constructor.
* A more elaborate description of the constructor.
*/
Test();
/**
* A destructor.
* A more elaborate description of the destructor.
*/
~Test();
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
/**
* A pure virtual member.
* @see testMe()
* @param c1 the first argument.
* @param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
/**
* a public variable.
* Details.
*/
int publicVar;
/**
* a function variable.
* Details.
*/
int (*handler)(int a,int b);
};
