Doxygen 使用总结

1.1 使用Doxygen我需要做什么

使用Doxygen生成文档，主要是两件事：
   1. 写一个配置文件（Doxyfile）。一般用Doxywizard生成后，再手工修改。

   2. 按照Doxygen的约定，将代码“文档化”。

然后只要执行命令：
doxygen Doxyfile

就可以了。输入文件、输出目录、参数等都是在Doxyfile中配置的。

1.2 得到什么

Doxygen的输出格式主要有HTML、LATEX、RTF等：

    * Doxygen在输出HTML文档时，可以自动准备用于制作CHM的项目文件（.hhp）、目录文件（.hhc）和索引文件（.hhk）。用HTML Help Workshop中的CHM编译器（hhc.exe）编译后生成CHM文件。
    * Doxygen在输出LATEX文档的同时准备了转换到pdf格式的makefile。只要系统安装了合适的TEX工具，就可以从LATEX文档生成pdf文档。
    * Doxygen输出的RTF格式，已经针对Word作了优化，可以较好地转换到Word文档。

2. doxygen配置文件
doxygen配置文件的格式是也是通常的unix下配置文件的格式：注释'#'开始；tag = value [,value2…]；对于多值的情况可以使用 tag += value [,value2…]。

对doxygen的配置文件的修改分为两类：

一种就是输出选项，控制如何解释源代码、如何输出；

一种就是项目相关的信息，比如项目名称、源代码目录、输出文档目录等。

对于第一种设置好后，通常所有项目可以共用一份配置，而后一种是每个项目必须设置的。

下面选择重要的，有可能需要修改的选项进行解释说明，其他选项在配置文件都有详细解释。

TAG 缺省值 含义
PROJECT_NAME        //项目名称
PROJECT_NUMBER     //可以理解为版本信息
OUTPUT_DIRECTORY // 输出文件到的目录，相对目录（doxygen运行目录）或者绝对目录
INPUT                   // 代码文件或者代码所在目录，使用空格分割
FILE_PATTERNS      //  *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl 指定INPUT                                      的目录中特定文件，如：*.cpp *.c *.h
RECURSIVE NO     //是否递归INPUT中目录的子目录
EXCLUDE             //在INPUT目录中需要忽略的子目录
EXCLUDE_PATTERNS   //明确指定的在INPUT目录中需要忽略的文件，如：FromOut*.cpp

OUTPUT_LANGUAGE    //English 生成文档的语言，当前支持2、30种语言，国内用户可以设置为Chinese
USE_WINDOWS_ENCODING  // YES（win版本）
                                      // NO（unix版本） 编码格式，默认即可。
EXTRACT_ALL      //NO 为NO，只解释有doxygen格式注释的代码；为YES，解析所有代码，即使没有注释。类的私有成员和所有的静态项由                                           //EXTRACT_PRIVATE和 EXTRACT_STATIC控制
EXTRACT_PRIVATE         //NO 是否解析类的私有成员
EXTRACT_STATIC          //NO 是否解析静态项
EXTRACT_LOCAL_CLASSES      //YES 是否解析源文件（cpp文件）中定义的类
SOURCE_BROWSER     //NO 如果为YES，源代码文件会被包含在文档中
INLINE_SOURCES       //NO 如果为YES，函数和类的实现代码被包含在文档中
ALPHABETICAL_INDEX     // NO 生成一个字母序的列表，有很多类、结构等项时建议设为YES
GENERATE_HTML      // YES 是否生成HTML格式文档
GENERATE_HTMLHELP   // NO 是否生成压缩HTML格式文档（.chm）
GENERATE_LATEX       // YES 是否乘车latex格式的文档
GENERATE_RTF  // NO 是否生成RTF格式的文档
GENERATE_MAN  // NO 是否生成man格式文档
GENERATE_XML   // NO 是否生成XML格式文档

3. doxygen注释
3.1 注释风格
下面是工作量最大部分，安装doxygen格式写注释。通常代码可以附上一个注释块来对代码进行解释，一个注释块由一行或者多行组成。通常一个注释块包括一个简要说明（brief）和一个详细说明（detailed），这两部分都是可选的。可以有多种方式标识出doxygen可识别的注释块。

我主要使用JavaDoc类型的注释风格（应用在C语言当中）

类似于由C风格的注释块： /**
* ... 文本 ...
*/

3.2 doxygen常用注释格式
通常的选择上面的一、两种注释风格，遇到头文件中各种类型定义，关键变量、宏的定义，在其前或者后使用 @brief 定义其简要说明，空一行后继续写其详细的注释即可。

对函数的注释，是比较常常需要注释的部分。除了定义其简要说明以及详细注释，还可以使用param命令对其各个参数进行注释，使用return命令对返回值进行注释。常见的格式如下：

int func1(int a, int b);

进行设计时，通常有模块的概念，一个模块可能有多个类或者函数组成，完成某个特定功能的代码的集合。如何对这个概念进行注释？doxygen提供了group的概念，生成的模块的注释会单独放在一个模块的页面中。使用下面的格式定义一个group。

code

group中的代码可以有自己的注释。单纯定义一个模块，去除{ 和}命令即可。任何其他代码项（比如类、函数、甚至文件）如果要加入到某个模块，可以在其doxygen注释中使用ingroup命令即可。Group之间使用ingroup命令，可以组成树状关系。

把多个代码项一起添加到某个模块中可以使用addtogroup命令，格式和defgroup相似。

对于某几个功能类似的代码项（比如类、函数、变量）等，如果希望一起添加注释，而又不想提升到模块的概念，可以通过下面的方式：
对这种组进行命名可以使用name命令。此时中间代码可以有自己的注释。如：

/**
 * @defgroup module_flag PPE_FLEXIBLE_PACKET_CLASSIFIER
 * @{
 */

code…                                                                                                                                                                                         

/**
 * @}
 */   

注释示例：

/**
* @par Description
* This function gets the pointer of acl entry.
* @param fid - 0 is FPC0, 1 is FPC1, 2 is FPC2
* @param aclId - acl Id, FPC0: 0~4095, FPC1: 0~2047, FPC2: 0~4095
* @param acl - acl entry
*
* @return OPL_OK - on success
* @return OPL_ERROR - on error
* @see
*/

                                                                                                                                                                                                                                                                                                                                                                         

3.3 doxygen常用注释命令
doxygen通过注释命令识别注释中需要特殊处理的注释，比如函数的参数、返回值进行突出显示。

@exception <exception-object> {exception description} 对一个异常对象进行注释。
@warning {warning message } 一些需要注意的事情
@todo { things to be done } 对将要做的事情进行注释
@see {comment with reference to other items } 一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。
@relates <name> 通常用做把非成员函数的注释文档包含在类的说明文档中。
@since {text} 通常用来说明从什么版本、时间写此部分代码。
@deprecated
@pre { description of the precondition } 用来说明代码项的前提条件。
@post { description of the postcondition } 用来说明代码项之后的使用条件。
@code 在注释中开始说明一段代码，直到@endcode命令。
@endcode 注释中代码段的结束。
@addtogroup 添加到一个组。
@brief  概要信息
@deprecated 已废弃函数
@details  详细描述
@note  开始一个段落，用来描述一些注意事项
@par  开始一个段落，段落名称描述由你自己指定
@param  标记一个参数的意义
@code .. @endcode 包含一段代码
@fn  函数说明
@ingroup 加入到一个组
@return  描述返回意义
@retval  描述返回值意义
@include 包含文件

到此为止，常用的doxygen的注释格式讨论完毕，我们能够按照一定的格式撰写doxygen认识的注释，并能够使用doxygen方便快捷的生成对应的文档，不过注释中应该写些什么，如何撰写有效的注释可能是困扰开发人员的一个更深层次的问题。

下面是在网上搜集到的一些问题，也一并记录在此：

如何编译成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，保存，编译即可。

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

 

如何去掉CHM附带的CHI文件？
注意在默认情况下，CHM会有一个CHI文件，似乎是用来加速索引的。我本人也遇到过很多用户仅仅上传了CHM，而没有上传CHI文件，导致无法正常显示 的情况。我不知道是否可以通过工具重建CHI文件，但是我觉得关闭这个功能即可。打开[Expert...]的HTML页面，取消 GENERATE_CHI即可。

 

如何像MSDN那样右边每页显示一个函数？
这个问题其实比较棘手，在[Expert...]中的Project页面，下面有一个选项叫做SEPARATE_MEMBER_PAGES，把这个选项选 中，这样每个函数就是一个页。但是会有一个问题，那就是右边页面的旁边多了所有函数的列表。很遗憾，经过研究，这个确实无法去掉。我的解决方法就是自己编 译一下doxygen，在memberlist.cpp的writeDocumentationPage函数中将 container->writeQuickMemberLinks(ol,md);连同附近几行屏蔽掉即可。

 

如何在CHM中去掉当选择SUBGROUPING后去掉分组的组信息？

        这个功能就是在chm的左边树中直接列出函数列表，而不用点击看右边页面了。这个功能需要修改源代码。在index.cpp中，屏蔽 writeGroupIndexItem函数的 Doxygen::indexList.addContentsItem，Doxygen::indexList.incContentsDepth和 Doxygen::indexList.decContentsDepth();即可，具体不解释了，一看便知。

 

如何修改或者去掉右下脚Generated at ...的文字？
       打开[Expert...]的HTML页面，然后在HTML_FOOTER中指定相应的HTML文件即可。注意HTML_FOOTER中至少包含BODY 和HTML结束标记。即一个最小的尾部HTML至少是这样</BODY></HTML>。同理，如果你要指定了 HTML_HEADER，他至少包含<HTML><HEAD></HEAD><BODY>

如何生成组？
组就是可以把同类的函数放到一个根下的显示方式。doxygen支持grouping，即你可以把相关的代码通过标志，放到同一个组中，便于查看。这主要 是通过几个内置语法命令。首先通过@defgroup定义一个组，然后要把分组的函数或者类等，通过标志@ingroup加入相应的组。这样，相应的函数 就被放置在同一个组中。

 

如何生成中文帮助？

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

 

如何彻底解决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生成，网上有篇文章介绍过，我测试一下，也是没有问题的。

         Doxygen可以通过Graphviz开源工具的支持来画出各种图形插入文档中，包括文件include关系、对象继承关系等

更为强大的是，Doxygen生成的这些图形支持交互导航功能（在HTML格式下有效），文档用户只需点击即可切换到相应的页面，十分方便，而所有的这些只需要设置下面这几个简单的配置选项即可：

DOT_PATH               =  #Graphviz路径

DOT_IMAGE_FORMAT       =  #图片格式，默认是PNG

CLASS_DIAGRAMS         =  #是否画类图

COLLABORATION_GRAPH    =  #是否画协作图

UML_LOOK               =  #使用UML风格

INCLUDE_GRAPH          = #include关系

CALL_GRAPH             =  # 调用图

GRAPHICAL_HIERARCHY    = #继承关系图

下面是window下面输出chm的图像操作记录：

 输出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，保存，编译即可。

HHC_LOCATION中输入hhc.exe文件的路径。hhc.exe可以通过安装HTML Help Workshop获得。

HTML Help Workshop 地址：

http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

4 如何像MSDN那样在左边的树中显示函数列表？

打开[Expert...]的HTML页面，然后选中TOC_EXPAND即可。

5 如何去掉CHM附带的CHI文件？

注 意在默认情况下，CHM会有一个CHI文件，似乎是用来加速索引的。我本人也遇到过很多用户仅仅上传了CHM，而没有上传CHI文件，导致无法正常显示的 情况。我不知道是否可以通过工具重建CHI文件，但是我觉得关闭这个功能即可。打开[Expert...]的HTML页面，取消GENERATE_CHI 即可。

6 如何像MSDN那样右边每页显示一个函数？

这个问题其实比较棘手，在[Expert...]中的 Project页面，下面有一个选项叫做SEPARATE_MEMBER_PAGES，把这个选项选中，这样每个函数就是一个页。但是会有一个问题，那就 是右边页面的旁边多了所有函数的列表。很遗憾，经过研究，这个确实无法去掉。我的解决方法就是自己编译一下doxygen，在 memberlist.cpp的writeDocumentationPage函数中将 container->writeQuickMemberLinks(ol,md);连同附近几行屏蔽掉即可。

7 如何在CHM中去掉当选择SUBGROUPING后去掉分组的组信息？

这 个功能就是在chm的左边树中直接列出函数列表，而不用点击看右边页面了。这个功能需要修改源代码。在index.cpp中，屏蔽 writeGroupIndexItem函数的 Doxygen::indexList.addContentsItem，Doxygen::indexList.incContentsDepth和 Doxygen::indexList.decContentsDepth();即可，具体不解释了，一看便知。

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

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

9 如何生成组？

组 就是可以把同类的函数放到一个根下的显示方式。doxygen支持grouping，即你可以把相关的代码通过标志，放到同一个组中，便于查看。这主要是 通过几个内置语法命令。首先通过@defgroup定义一个组，然后要把分组的函数或者类等，通过标志@ingroup加入相应的组。这样，相应的函数就 被放置在同一个组中。

10 如何生成中文帮助？

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

11 如何彻底解决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生成，网上有篇文章介绍过，我测试一下，也是没有问题的。

最后，doxygen是一个开源项目，并且支持vs2005项目，这样一来，如果你觉得哪里不顺手，完全可以把代码下载后自行编译。虽然我感觉doxygen的代码写的不能算是perfect，但是对于一个这样的工程，我们无论如何都需要一种敬意。祝好运~

这样，基本上就能够用doxygen生成漂亮的文档了。代码方面，doxygen支持多种格式的注释风格，根据manual选择自己喜欢的就好。