Doxygen规范及工具的简单应用

Doxygen工具的下载地址：https://sourceforge.net/projects/doxygen/files/

一、对与C++程序的说明文档，一致推荐使用Doxygen工具，先说一下C++程序的注释说明规范，这只是其中的一种

1.所有注释都可以使用///开始(C++风格)。

2.函数注释方式

/// Constructor【函数描述】

/// @param [in] pos The position of Camera in world coordinate 【参数描述1】

/// @param [in] lookat The point Camera looks at in world coordinate 【参数描述2】

BaseCamera( const D3DXVECTOR3& pos, const D3DXVECTOR3& lookat );

3.变量注释方式

D3DXVECTOR3 m_Position; /*!< Camera position point in world coordinate */ 或

D3DXVECTOR3 m_Position; ///< Camera position point in world coordinate

两种方式产生的结果不同。前者会单独产生一块Member Data Documentation注释，后者会在Pubilc/Protected/Private Attributes变量描述后紧跟注释。

4.@参数和\参数相同

5.产生描述顺序和注释顺序相同，一般风格为

/// 函数描述

/// @param 参数描述

/// @return 返回值描述

/// @retval 返回值1 返回值1描述

/// @retval 返回值2 返回值2描述

/// @remarks 注意事项

/// @note 注意事项，功能同@remarks,显示字样不同

/// @par 自定义图块，后面可跟示例代码之类

/// @code(必须使用@endcode结束)

/// 示例代码(无需缩进)

/// @endcode

/// @see 其他参考项【产生指向参考的链接】

函数代码声明

6.特殊符号

/// - 产生一个黑色圆点

7.定义在类体里面的enum

/// Camera types

enum CAMERA_TYPE

{

CAMERA_FIRST_VIEW,/*!< Camera that looks from the first view */

CAMERA_MODEL_VIEW,///< Camera that looks from the third view

};

两种风格相同。

二、Doxygen工具的简单使用说明

下载地址：https://sourceforge.net/projects/doxygen/files/

Doxygen 产生文档可以分为三个步骤。

一是在程序代码中加上符合Doxygen所定义批注格式。

二是使用Doxywizard进行配置。

三是使用Doxygen来产生批注文档。

1.Doxygen 主界面如下图 1 所示。

说明：1，Doxygen 工作目录，就是用来存放配置文件的目录。

2，递归搜索源文件目录需要选上。

2.选择 wizard 标签下的 Output Topics

相关配置说明如下图 2 所示。

3.选择 wizard 标签下的 Diagrams Topics

相关配置说明如下图 3 所示。



说明：如果选择这个选项之前需要先安装了 Graphviz 工具包。

4.选择 expert 标签下的 Project Topics

相关配置说明如下图 4 所示。



说明：编码格式，UTF-8 是首选。如果需要显示中文则选择GB2312.

TAB_SIZE 主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议设置成4。

OPTIMIZE_OUTPUT_FOR_C 这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。如果

是纯C代码，建议选择。
SUBGROUPING这个选项选择后，输出将会按类型分组。

5.选择 expert 标签下的 Build

Build页面，这个页面是生成帮助信息中比较关键的配置页面：

EXTRACT_ALL 表示：输出所有的函数，但是private和static函数不属于其管制。

EXTRACT_PRIVATE 表示：输出private函数。

EXTRACT_STATIC 表示：输出static函数。同时还有几个EXTRACT，相应查看文档即可。

HIDE_UNDOC_MEMBERS 表示：那些没有使用doxygen格式描述的文档（函数或类等）就不显示了。当然，如果EXTRACT_ALL被启用，那么这个标志其实是被忽略的。

INTERNAL_DOCS 主要指：是否输出注解中的@internal部分。如果没有被启动，那么注解中所有的@internal部分都

将在目标帮助中不可见。

CASE_SENSE_NAMES 表示：是否关注大小写名称，注意，如果开启了，那么所有的名称都将被小写。对于C/C++这种

字母相关的语言来说，建议永远不要开启。

HIDE_SCOPE_NAMES 表示：域隐藏，建议永远不要开启。

SHOW_INCLUDE_FILES 表示：是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列

表。

INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。

SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显

示。

GENERATE_TODOLIST ：是否生成TODOLIST页面，如果开启，那么包含在@todo注解中的内容将会单独生成并显

示在一个页面中，其他的GENERATE选项同。

SHOW_USED_FILES ：是否在函数或类等的帮助中，最下面显示函数或类的来源文件。

SHOW_FILES ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

6.选择 expert 标签下的 Input Topics

相关配置说明如下图 5 所示。



说明：输入的源文件的编码，要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。

总结：

我查看到我的代码文件是GB2312的（查看方法（以VS2008为例）：文件->高级保存选项)。此时如果这里还是选择UTF-8，那么会导致编译出来的CHM文件中的中文会有乱码。

7.选择 expert 标签下的 HTML Topics

相关配置说明如下图 6 所示。



说明：1，CHM_FILE文件名需要加上后缀（xx.chm）。

2，如果在 Wizard 的 Output Topics 中选择了 prepare for compressed HTML (.chm)选项，此处就会要求选择 hhc.exe 程序的位置。在 windows help workshop 安装目录下可以找到 hhc.exe。

3，为了解决DoxyGen生成的CHM文件的左边树目录的中文变成了乱码，CHM_INDEX_ENCODING中输入GB2312即可。

4，GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。

5，TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。

8.选择 Run 标签

相关配置说明如下图 7 所示。



点击 Run doxygen 按钮， Doxygen 就会从源代码中抓取符合规范的注释生成你定制的格式的文档。