标签：
自己已将学习了两三次了吧，差不多这次该总结一下：
Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。
Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。Doxygen 就是在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文档了。因此，Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文档。
参考的博文有：http://sunzhennian.blog.163.com/blog/static/1951730712011112210184592/
http://blog.csdn.net/flatcd/article/details/138678
http://blog.csdn.net/u012501459/article/details/37668893
http://blog.csdn.net/bigpudding24/article/details/45247357
各有各得点，自己在总结。
使用步骤
1、第一次使用需要安装doxygen的程序
2、生成doxygen配置文件
3、编码时，按照某种格式编写注释
4、生成对应文档
1.1Doxygen下载
http://sourceforge.net/projects/doxygen/?source=dlp 进行下载
本文使用的为Doxygen 1.8.3.1
安装，我们将在配置的时候使用doxywizard，Doxygen的GUI版本。
1.2HTML Help Workshop下载
如果你希望你的Doxygen自动生成chm，那么请下载HTML Help Workshop，我们将要使用当中的hcc.exe文件以及相关dll
http://www.microsoft.com/en-us/download/details.aspx?id=21138 进行下载
下载其中的htmlhelp.exe并安装，记住安装目录，我们将在Doxygen配置时使用。
1.3 Graphviz
graphviz 是一个由AT&T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图，如不需要此功能可不安装该工具包。
安装并记录安装目录，同样我们一会需要配置Doxygen
具体的作用是下面的：包括怎么生产Doxygen
首先在网上下载Doxygen，HTML Help Workshop。这两个软件直接在各自的官网上下载就行了。
然后使用doxywizard.exe生成一个Doxygen文件。点击“D:\program files\Doxygen\doxygen\bin\doxywizard.exe”出现如下界面：在Wizard属性页主要需要改一个地方，点击左侧的“Output”将右侧复选框中的LaTex中的钩去掉；然后在Step1:下面指定Doxygen的工作目录，就是这个向导生成的文件的存放路径。
在"Wizard"和“Export”中还有许多可以编辑的参数，暂时不修改，以后熟悉了再改。然后点击“Run”下面的“Run doxygen”就可以生成了脚本。
再点击“File”菜单中的"Save as"，就可以生成我们需要的脚本了，将生成的脚本命名为default.doxygen如图：
default.doxygen就是普通的文本文件，在这里需要对它进行一些编辑，这些需要编辑的地方主要是字符编码的问题，其实在前面的图形化界面中也可以进行更改的。
主要需要修改的地方有如下几处：
GENERATE_HTMLHELP = YES
OUTPUT_LANGUAGE = Chinese
CHM_INDEX_ENCODING = gb2312
DOXYFILE_ENCODING=gb2312
INPUT_ENCODING=gb2312
然后这个default.doxygen就处理好了。
接下来是在vs中集成这些工具方便以后使用了。将default.doxygen拷贝到需要生成文档的工程下面
1．集成Doxygen
在VS环境中：Tools->External Tools->Add
Title: Doxygen
Command: D:\Program Files\doxygen\bin\doxygen.exe（doxygen的安装目录）
Arguments: $(ProjectDir)\default.doxygen
Initial directory: $(ProjectDir)
（可以把use output window复选框勾上）
点击Tools->Doxygen，将会在工程目录下生成html文件夹，里面的html文件就是自动生成的注释文件。
2．集成CHM制作工具HTML Help Workshop
首先安装HTML Help Workshop。
在VS环境中：Tools->External Tools->Add
Title: HTML Help Workshop
Command: D:\program files\Doxygen\htmlhelp\hhw.exe（HHW的安装目录）
Arguments: $(ProjectDir)html\index.hhp
Initial directory: $(ProjectDir)
点击Tools->HTML Help Workshop，就会出现HHW的窗体，编译，可得到index.chm文件。
注意：编译时，会弹出一个窗口确认路径名，而VS自动传入的路径名是有错误的，多了2个双引号，去掉双引号，编译，就可以成功了。如下图：
3．集成CHM文件查看工具hh.exe
在VS环境中：Tools->External Tools->Add
Title: ViewCHM
Command: C:\WINDOWS\hh.exe（windows自带）
Arguments: $(ProjectDir)html\index.chm
Initial directory:
点击Tools-> ViewCHM，就会看到index.chm文件了。
如果只要Html的注释，应该不用安装后面的两个了！
2.1基本配置
在基本配置中，会介绍一些关于Doxygen的基本配置，例如各种乱码，输出内容等。
首先我们打开开始-》所有程序-》Doxygen-》doxywizard
第一步，选择你的工作目录（配置文件位置 D:\Doxygen），点击Select。
第二步，进行配置
Wizard选项卡：
首先修改Project name，选择扫描源代码的目录，Source code directory：，勾选Scan recursively （递归扫描），之后选择输出目录，作为测试选择桌面进行查看。
在Wizard的Topics下的Mode，选择All Entities，可以输出相对完整的功能，是否包含源代码看你自身情况，在下面选择好你的语言。这里作者使用的是C# 所以选择Java or C#
在Output中，如果你需要输出chm格式，请勾选。
在Diagrams中选择使用GraphViz包，来输出UML
Expert选项卡：
说明：编码格式，UTF-8 是首选。如果需要显示中文则选择GB2312.
TAB_SIZE 主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议设置成4。
Build页面，这个页面是生成帮助信息中比较关键的配置页面：
EXTRACT_ALL 表示：输出所有的函数，但是private和static函数不属于其管制。
EXTRACT_PRIVATE 表示：输出private函数。
EXTRACT_STATIC 表示：输出static函数。同时还有几个EXTRACT，相应查看文档即可。
SHOW_INCLUDE_FILES 表示：是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列
表。
INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。
SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显
示。
说明：INPUT_ENCODING (输入的源文件的编码)，要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。
总结：我查看到我的代码文件是utf-8的（vs2013中打开文件 选另存为可看到编码格式）（（VS2012的话）：文件->高级保存选项)。
在Expert的HTML中，首先要看HHC_LOCATION选项，添加安装目录（注：作者目录为C:/Program Files (x86)/HTML Help Workshop/hhc.exe）
勾选CHM_INDEX_ENCODING，在你源代码中的字符集是什么就填写什么，
之后在Expert的Dot中勾选CLASS_DIAGRAMS,UML_LOOK
为了减少chm体积，在DOT_IMAGE_FORMAT中选择gif或者jpg，均可。
最后选择好DOT_PATH所输出的位置。
Error: When enabling GENERATE_HTMLHELP the search engine (SEARCHENGINE) should be disabled. I‘ll do it for you.
warning: The selected output language "chinese" has not been updated
since release 1.8.2. As a result some sentences may appear in English.
解决：把HTML里面的SEARCHENGINE设置为NO
并非所有程序代码中的批注都会被Doxygen 所处理。您必需依照正确的格式撰写。原则上，Doxygen 仅处理与程序结构相关的批注，如
Function，Class ，档案的批注等。对于Function内部的批注则不做处理。Doxygen可处理下面几种类型的批注。
JavaDoc类型：
/**
* ... 批注 ...
*/
Qt类型：
/*!
* ... 批注 ...
*/
单行型式的批注：
/// ... 批注 ...
或
//! ... 批注 ...
要使用哪种型态完全看自己的喜好。以笔者自己来说，大范围的注解我会使用JavaDoc 型的。单行的批注则使用"///" 的类型。
此外，由于Doxygen 对于批注是视为在解释后面的程序代码。也就是说，任何一个批注都是在说明其后的程序代码。如果要批注前面的程
式码则需用下面格式的批注符号。
/*!< ... 批注 ... */
/**< ... 批注 ... */
//!< ... 批注 ...
///< ... 批注 ...
上面这个方式并不适用于任何地方，只能用在class 的member或是function的参数上。
举例来说，若我们有下面这样的class。
class MyClass {
public:
int member1 ;
int member2:
void member_function();
};
加上批注后，就变成这样：
/**
* 我的自订类别说明 ...
*/
class MyClass {
public:
int member1 ; ///< 第一个member说明 ...
int member2: ///< 第二个member说明 ...
int member_function(int a, int b);
};
/**
* 自订类别的member_funtion说明 ...
*
* @param a 参数a的说明
* @param b 参数b的说明
*
* @return 传回a+b。
*/
int MyClass::member_function( int a, int b )
{
return a+b ;
}
当您使用Doxygen 产生说明文档时，Doxygen 会帮您parsing 您的程式码。并且依据程序结构建立对应的文件。然后再将您的批注，依据其位置套入于正确的地方。您可能已经注意到，除了一般文字说明外，还有一些其它特别的指令，像是@param及@return 等。这正是Doxygen 另外一个重要的部分，因为一个类别或是函式其实都有固定几个要说明的部分。为了让Doxygen 能够判断，所有我们就必需使用这些指令，来告诉Doxygen 后面的批注是在说明什么东西。Doxygen 在处理时，就会帮您把这些部分做特别的处理或是排版。甚至是制作参考连结。
首先，我们先说明在Doxygen 中对于类别或是函数批注的一个特定格式。
/**
* class或function的简易说明...
*
* class或function的详细说明...
* ...
*/
上面这个例子要说的是，在Doxygen 处理一个class 或是function注解时，会先判断第一行为简易说明。这个简易说明将一直到空一行的出现。或是遇到第一个"." 为止。之后的批注将会被视为详细说明。两者的差异在于Doxygen 在某些地方只会显示简易说明，而不显示详细说明。如：class 或function的列表。
另一种比较清楚的方式是指定@brief的指令。这将会明确的告诉Doxygen，何者是简易说明。例如：
/**
* @brief class或function的简易说明...
*
* class或function的详细说明...
* ...
*/
除了这个class 及function外，Doxygen 也可针对档案做说明，条件是该批注需置于档案的前面。主要也是利用一些指令，通常这部分注解都会放在档案的开始地方。如：
/*! \file myfile.h
\brief 档案简易说明
详细说明.
\author 作者信息
*/
如您所见，档案批注约略格式如上，请别被"\" 所搞混。其实，"\" 与"@" 都是一样的，都是告诉Doxygen 后面是一个指令。两种在Doxygen 都可使用。笔者自己比较偏好使用"@"。
接着我们来针对一些常用的指令做说明：
|
@file |
档案的批注说明。 |
|
@author |
作者的信息 |
|
@brief |
用于class 或function的批注中，后面为class 或function的简易说明。 |
|
@param |
格式为 @param arg_name 参数说明 主要用于函式说明中，后面接参数的名字，然后再接关于该参数的说明。 |
|
@return |
后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。 |
|
@retval |
格式为 @retval value 传回值说明 主要用于函式说明中，说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。 |
Doxygen 所支持的指令很多，有些甚至是关于输出排版的控制。您可从Doxygen的使用说明中找到详尽的说明。
下面我们准备一组example.h 及example.cpp 来说明Doxygen 批注的使用方式：
example.h:
/**
* @file 本范例的include档案。
*
* 这个档案只定义example这个class。
*
* @author garylee@localhost
*/
#define EXAMPLE_OK 0 ///< 定义EXAMPLE_OK的宏为0。
/**
* @brief Example class的简易说明
*
* 本范例说明Example class。
* 这是一个极为简单的范例。
*
*/
class Example {
private:
int var1 ; ///< 这是一个private的变数
public:
int var2 ; ///< 这是一个public的变数成员。
int var3 ; ///< 这是另一个public的变数成员。
void ExFunc1(void);
int ExFunc2(int a, char b);
char *ExFunc3(char *c) ;
};
example.cpp:
/**
* @file 本范例的程序代码档案。
*
* 这个档案用来定义example这个class的
* member function。
*
* @author garylee@localhost
*/
/**
* @brief ExFunc1的简易说明
*
* ExFunc1没有任何参数及传回值。
*/
void Example::ExFunc1(void)
{
// empty funcion.
}
/**
* @brief ExFunc2的简易说明
*
* ExFunc3()传回两个参数相加的值。
*
* @param a 用来相加的参数。
* @param b 用来相加的参数。
* @return 传回两个参数相加的结果。
*/
int ExFunc2(int a, char b)
{
return (a+b);
}
/**
* @brief ExFunc3的简易说明
*
* ExFunc3()只传回参数输入的指标。
*
* @param c 传进的字符指针。
* @retval NULL 空字符串。
* @retval !NULL 非空字符串。
*/
char * ExFunc2(char * c)
{
return c;
}
标签：
原文地址：http://www.cnblogs.com/ranjiewen/p/5361138.html
