前言
下面主要讲解linux下Doxygen命令行实现html文档生成的操作，当然也有界面版本操作方式，linux下安装doxygen-gui即可通过doxywizard开启界面操作，windows下也可以通过doxywizard.exe界面进行配置操作，具体的界面操作请参考其他网上文章，不过有一句话需要说明：会命令行操作的，应该都会界面操作，而会界面操作的就不一定会命令行操作了。
windows下的操作方式可以参考 使用doxygen生成chm范例
doxygen是什么
按照约定的格式注释源代码，用工具处理注释过的源代码产生文档。通过这种方式产生文档至少有以下好处：
- 便于代码和文档保持同步
- 可以对文档做版本管理
Doxygen就是这样的工具，Doxygen是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。很多编程语言都有类似的文档工具，例如：Java有javadoc，Ruby有rdoc。对于C/C++程序，我们可以用Doxygen生成文档。Doxygen有如下特点：
- 支持的编程语言：完全支持 C、C++、Java、IDL、Objective-C、Python、PHP、C#、Fortran、VHDL
- 输出格式：直接支持 HTML、Latex、RTF、manpage、Qt help project、XML，间接支持 chm、
Qt Compressed Help、Postcript和PDF； - 兼容 JavaDoc、Qt-Doc、KDOC等类似工具；
- 支持平台：Unix（包括Linux）、MacOs、Windows等；
主页：http://www.doxygen.org/
邮件列表：
doxygen-user@lists.sourceforge.net
doxygen-develop@lists.sourceforge.net
作者：Dimitri van Heesch (dimitri@stack.nl) ；
Doxygen基本操作流程
- 按照Doxygen的约定，将代码“文档化”。这部分请参考 代码‘文档化’；
- 编写一个配置文件（Doxyfile），用于配合Doxygen生成最终的文档。这部分请参考 编写一个Doxygen配置文件；
- 执行doxygen Doxyfile生成文档。
下面详细介绍每一个步骤。
代码‘文档化’
这一部分需要了解基本的注释规则和doxygen注释标记
doxygen注释规则
并非所有程序代码中的注释都会被 Doxygen 处理(除非在配置文件里使能了EXTRACT_ALL等选项)，必需依照正确的格式撰写，Doxygen 可处理下面两种类型的注解(注意：默认采用的JavaDoc风格，你也可以选择采用Qt或者c/c++风格),如下:
/**
* ...多行注释...
*
*/
/** ...单行注释... */
由于 Doxygen 认为注释是说明它下面的程序代码。所以,如果注释要与前面的程序码在同一行内,则需用下面这种型式的注释:
/**< ...代码同行情况的注释 */
注意,除**后多了一个<,其它的与前面相同。
首先,我们先说明在 Doxygen 中对於类别或是函数注解的一个特定格式。
/**
*
* struct、class、functiond的简易说明...
*
* struct、class、functiond的详细说明...
* ...
*/
上面这个例子要说的是,在 Doxygen 处理一个类定义或是函数定义之上的注释时:
会先判断第一行为简易说明,这个简易说明将一直到遇见一个空白行的出现或是遇到第一个 . 为止;
之后的注解将会被视为详细说明。
另一种比较清楚的方式是指定@brief 的指令,这将会明确的告诉 Doxygen 哪个是简易说明。
doxygen在处理注释文档的时候，会进行如下的过程：
- 执行在文档中的特殊命令。命令都以''或'@'开始,二者是一样的，都是为了引出一个命令。例如'rief','details','@brief', '@details'等等。
- 如果一行以空白开始，后面跟着一个或者多个''，然后又跟着0个或者多个空白，那么所有的空白和''将会被移除。
- 所有的空行将会被当作段分隔符号。
- 为相应的被文档化了的类的单词创建相应的链接（除非这个单词前面放置一个'%'，这时候就没有链接了并且'%'也会被移走了）。
- 如果在文本中发现了相应的匹配，会建立成员的链接。(?)
- 文档中的HTML标记会被解释、转化为LATEX的东西以便成为LATEX的输出。(?)
Doxygen常用的代码注释标记
- 文件信息
@file 文件名(遵守文件命名规则) --> 文件声明，即当前文件名
@author 作者名 --> 作者
@version 版本号 --> 版本号
@todo 说明文字 --> TODO 列表，在相关页面有它专门一项
注:只能在实现文件(.c/.cpp)中使用，如果相同函数的实现文件与头文件中均有，生成的文档中会有重复项，可以理解为调用者不应知道实现流程
@date 日期时间 --> 说明文件生成的日期时间
@section 章节标题 --> @section LICENSE 版权许可 @section DESCRIPTION 描述 - 模块信息
@defgroup 模块名(英文) 显示名(中文) @{ 类/函数/变量/宏/... @}--> 定义模块
@ingroup 模块名(英文) [显示名(中文)]--> 作为指定名的模块的子模块,显示名为可选项,可与指定名的模块的显示名不同
@addtogroup 模块名(英文) [显示名(中文)] --> 作为指定名的模块的成员,显示名为可选项,必需与指定名的模块的显示名相同
@name 显示名(中文) @{ 变量/宏 @} --> 按用途分,以便理解全局变量/宏的用途
这部分推荐参考： doxygen使用总结 - 函数信息
@param 参数名 说明文字 --> 不建议使用这个
@param[in] 参数名 说明文字 --> 输入参数
@param[out] 参数名 说明文字 --> 输出参数
@param[in,out] 参数名 说明文字 --> 即输入又输出参数
@exception 用来说明异常类及抛出条件
@remark 表示评论，暴露给客户程序员的文档
@return 说明文字 --> 返回值说明
@retval 说明文字 --> 特定返回值说明
@note 说明文字 --> 注解,可以描述工作流程和注意事项
@par [段落标题] --> 开创新段落,一般与示例代码联用
@code --> 示例代码开始
@endcode --> 示例代码结束
@see 类/函数/变量/文件/URL --> 参见,
类名::函数名 或 ::函数名 可以变成超链接点击跳转到对应函数说明处
函数重载的情况下,要带上参数列表以及返回值
@deprecated 说明文字 --> 过时列表,在相关页面有它专门一项
注:只能在头文件(*.h)中使用,如果相同函数的实现文件与头文件中均有,
生成的文档中会有重复项,可以理解为维护者不关心这个接口是不是要过时
@pre 说明文字 --> 前置条件
@arg 参数/返回值 说明文字 --> 以列表形式说明参数取值意义
注:也可以用 - 或 -# 来代替,建议此种方法,简单明了
- 第一级
- 第二级
- 第三级
即相同开头的-或-#第二行比第一行缩进一个英文空格就变了第二级,依次类推
-开头的第一级为实心黑圆点;第二级为空心黑圆点;第三级以后为实心方块;
-#开头的第一级为数字(1./2./3./...),
第二级为小写字母(a./b./c./...),
第三级为罗马数字(i./ii./iii./...),
第四级为大写字母(A./B./C./...) - 提醒信息
@brief 说明文字 --> 摘要,即当前文件/函数说明
@attention 说明文字 --> 注意
@bug 说明文字 --> 问题
@warning 说明文字 --> 警告
@ref 引用其他标记，类似于html中的锚
@since {text} 通常用来说明从什么版本、时间写此部分代码
@relates通常用做把非成员函数的注释文档包含在类的说明文档中
@def 宏定义说明
@fn 函数 函数说明
@test 测试示例、信息
(@bug、@test以及@todo等会出现链接页面)
下面为生成特殊字体的命令：
@a @e @em：其后的单个字(word)表现为斜体，以强调作用。如有多个word的话，使用xxx xxx代替
@b：其后的word为粗体，多个则使用xxx xxx
@c @p：字体表现为打印机字体，多个则使用xxx xxx
@enum 引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg：@enum CTest::MyEnum
@var 引用了某个变量，Doxygen会在该枚举处产生一个链接 eg：@var CTest::m_FileKey
@class 引用某个类，格式：@class
下面举例说明可能遇到的几种情况：
- 文件注释
/**
* @file
* @author rongp
* @version 1.0.0
* @date 2016/02/22
*
* @section LICENSE
*
* Copyright(c) 2015-2020 XXX
* All rights reserved
*
* @brief iss服务器端sdk导出根文件
*
* @section DESCRIPTION
* 界面开发者只需要包含该头文件即可, 具体的导出数据结构、api分别分别在
* net_io_export.h和app_amp_export.h中
*
*/
- 函数注释
/**
* @brief 创建与本地服务通讯的端点
* @param[in] proto_type 端点通讯采用的协议类型, 一般设置为PROTO_TYPE_TRANS即可
*
* @return 用于通讯的端点指针，作为后面接口的参数
* @retval non-NULL 成功
* @retval NULL 出错
*
* @warning 该接口只能在服务端sdk使用, 当前只支持PROTO_TYPE_TRANS协议类型
*
* 示例
@code
gpointer e = net_io_create_local_endpoint(PROTO_TYPE_TRANS);
@endcode
*
* @since 1.0.0
*/
- 结构体注释
/**
* @brief 服务器信息描述结构
*/
struct _ServerInfo {
/** 服务器系统版本, 包括硬件信息、操作系统信息等 */
gchar sys_ver[128];
/** 服务器软件版本 */
gchar soft_ver[128];
};
- 枚举注释
/**
* @brief 消息返回码
*/
enum MSG_RET_CODE {
/** 执行成功 */
MSG_EXECUTE_OK = 0,
/** 超时 */
MSG_TIMEOUT = -1,
/** 消息的大小有误 */
MSG_SIZE_UNMATCH = -2,
/** 不允许执行该消息 */
MSG_OPT_FORBID = -3,
/** 服务器端服务出错 */
MSG_SYSTEM_ERR = -4,
/** 消息的参数有误 */
MSG_ARG_INVALID = -5,
/** buf内存不够 */
MSG_NOMEM = -100,
};
编写一个Doxygen配置文件
一般是通过先生成模板配置文件，然后基于模板配置文件修改即可。使用 "doxygen -g" 命令在当前目录下生成名为‘Doxyfile’的配置文件模板。也可以采用 "doxygen -g filename" 命令格式指定所生成的配置文件名为filename。如无特殊需要，采用默认的配置文件名即可。如果对 Doxygen 各配置选项的意义有一定了解，可以在生成配置文件的命令中添加 "-s" 选项，生成不含注释的配置文件，如:doxygen -s -g 这种方式生成的配置文件非常精简，没有任何注释。
有了doxygen模板配置文件后，现在要做的就是对它进行修改了，下面以c语言开发的项目生成html为例。主要有下面几个选项需要修改：
# 项目名称，将作为于所生成的程序文档首页标题，需要使用双引号括住
PROJECT_NAME = “xxx”
# 文档版本号，可对应于项目版本号，譬如 git、svn、cvs 所生成的项目版本号
PROJECT_NUMBER = “1.0.0”
# 程序文档输出目录，产生的文件会放在这个路径之下。如果没有填这个路径，将会以当前所在路径来作为输出路径。
OUTPUT_DIRECTORY = doc/
# 程序文档语言环境，预设为 English。1.2.16 版后，可以用 Chinese 输出简体中文，也可以使用
# Chinese-Traditional 来输出中文繁体的格式。
OUTPUT_LANGUAGE = Chinese
# 如果是制作 C 程序文档，该选项必须设为YES，否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C = YES
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型，只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT = YES
# 把这个标记设置为Yes，即使各个类或函数没有文档，也要提取信息
EXTRACT_ALL = YES
# 把这个标记设置为Yes，文档就会包含类的私有数据成员
EXTRACT_PRIVATE = YES
# 把这个标记设置为Yes，文档就会包含文件的静态成员(函数和变量)
EXTRACT_STATIC = YES
# 在 C++ 程序文档中,该值可以设置为 NO，而在 C 程序文档中，由于 C 语言没有所谓的域/名字空间
# 这样的概念，所以此处设置为 YES
HIDE_SCOPE_NAMES = YES
# 让 doxygen 静悄悄地为你生成文档，只有出现警告或错误时，才在终端输出提示信息
QUIET = YES
# 这个标记创建一个以空格分隔的所有目录的列表，
# 这个列表包含需要生成文档的 C/C++ 源代码文件和头文件，可以不设定，即为当前目录!
INPUT = inc/
# 输入文件的编码格式，需要自己根据INPUT指定的文件选择，否则会乱码
INPUT_ENCODING = UTF-8
# 在默认情况下,doxygen 会搜索具有典型 C/C++ 扩展名的文件，
# 比如 .c、.cc、.cpp、.h 和 .hpp 。
# 可以使用如下形式的列表方式,指定INPUT下要处理的文件
# 注:文件类型后有空格然后是右斜杠然后回车,每一个文件类均独自一行!
# FILE_PATTERNS = *.h
*.c
*.cpp
FILE_PATTERNS =
# 递归遍历由 INPUT 所指定的目录及其所有子目录，寻找由 FILE_PATTERNS 指定的要被文档化的文件
RECURSIVE = YES
# 如果您有特定文件或目录，不希望经过 Doxygen 处理，那你可在这指出，没有就不指出
# 例如:EXCLUDE = /home/xxx/src_root /home/xxx/test
EXCLUDE =
# 类似于 FILE_PATTERNS 的用法，只是这个是供 EXCLUDE 所使用
EXCLUDE_PATTERNS =
# 若设定为 YES，就会产生 HTML 版本的说明文件。HTML 文件是 Doxygen 预设产生的格式之一
GENERATE_HTML = YES
# 若设定为 YES，Doxygen 会帮您产生一个树状结构，在页面左侧，默认为 NO
# 这个树状结构是以 JavaScript 所写成。所以需要新版的 Browser 才能正确显示。
GENERATE_TREEVIEW = YES
其他可参考的：
文档输出格式
除了 HTML 之外，doxygen 还可以生成几种输出格式的文档。可以让 doxygen 生成以下格式的文档：
UNIX 手册页：把 <GENERATE_MAN> 标记设置为 Yes。在默认情况下，会在 <OUTPUT_DIRECTORY> 指定的目录中创建 man 子文件夹，生成的文档放在这个文件夹中。必须把这个文件夹添加到 MANPATH 环境变量中。
Rich Text Format（RTF）：把 <GENERATE_RTF> 标记设置为 Yes。把 <RTF_OUTPUT> 标记设置为希望放置 .rtf 文件的目录；在默认情况下，文档放在 OUTPUT_DIRECTORY 中的 rtf 子文件夹中。要想支持跨文档浏览，应该把 <RTF_HYPERLINKS> 标记设置为 Yes。如果设置这个标记，生成的 .rtf 文件会包含跨文档链接。
Latex：在默认情况下，doxygen 生成 Latex 和 HTML 格式的文档。在默认的 Doxyfile 中，<GENERATE_LATEX> 标记设置为 Yes。另外，<LATEX_OUTPUT> 标记设置为 Latex，这意味着会在 OUTPUT_DIRECTORY 中创建 latex 子文件夹并在其中生成 Latex 文件。
Microsoft® Compiled HTML Help（CHM）格式：把 <GENERATE_HTMLHELP> 标记设置为 Yes。因为在 UNIX 平台上不支持这种格式，doxygen 只在保存 HTML 文件的文件夹中生成一个 index.hhp 文件。您必须通过 HTML 帮助编译器把这个文件转换为 .chm 文件。
Extensible Markup Language（XML）格式：把 <GENERATE_XML> 标记设置为 Yes。（注意，doxygen 开发团队还在开发 XML 输出）。
按照上面的修改后，就可以执行第三步，执行命令doxygen Doxyfile生成文档了。注意：这里的Doxyfile
为你实际的Doxygen配置文件名。
Doxygen与其他工具配合生成chm
参考 https://stackoverflow.com/questions/23680921/generate-chm-from-doxgen-results
Doxygen FAQ
6.1 中文问题：中文注释在文档中是乱码
解决：在expert中的INPUT选项页的INPUT_ENCODEING中填入“GB2312”，这样基于GB的文本编辑器生成的代码就可以正常使用了。
6.2 图形问题：无法绘制类图协作图等图形。
解决：首先确保安装了graphviz for win，注意不是wingraphviz，后者是一个graphviz的com封装，但是doxygen并不是基于它开发的，所以装了也没用。然后在expert的DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。
如果出现无法包含.map文件的错误，可以将工作目录设置成html，并将html中所有文件都清除再试。这个问题的原因还不太确定。
6.3 输出chm的问题：如何输出.chm文件
配置时注意expert中的HTML页：选中“GENERATE_HTMLHELP”，然后在CHM_FILE中填上想要的chm文件名。
HHC_LOCATION中输入hhc.exe文件的路径。hhc.exe可以通过安装HTML Help Workshop获得。
或者使用HTML Help Workshop来编译Doxygen生成的html文件夹中的.hhp文件，编译完成后即可在该html文件夹中找到对应的chm文件
6.4 Doxygen无法为DLL中定义的类 导出文档
例如：
class __declspec(dllexport) CClassName:public CObject
{
}
目前发现Doxygen无法识别出DLL中定义的类。
http://ticktick.blog.51cto.com/823160/188674
参考：
学习用 doxygen 生成源码文档
Doxygen使用指南 - Doxygen_Using_Manual.pdf
Doxygen: Main Page
Doxygen Manual: Getting started
未完，待续
2016年6月