Doxygen 代码文档生成工具的使用方法

为自己的工程建立文档是非常必要，这可以有效提高代码的开发和维护效率。

Doxygen是一个便捷的文档生成工具，它是一个GPL开源工程，使用的比较普遍。

它的特点是独立于特定的编程语言，支持C++、C、Java、Objective-C、Python等等，基本上可以满足所有编程语言。而且它有社区持续维护，我看到最近的版本更新时间是2012.08，就上个月。

使用方法(Mac版)

  1. 去Doxygen官网下载需要的Doxygen版本，并且安装。
  2. 运行Doxygen，按照提示使用，非常简单。

指定working deirectory，选择工程的路径即可。

使用Wizard Tab中的选项进行设置

输入工程名。(显示为HTML文档中的主标题) 
版本号 
logo图片 
选择代码目录 
选择文档的输出目录

选择All Entities Mode

选择输出文档的类型，HTML即可。

一切配置完成，选择Run Tab，Run doxygen输出文档即可。

注释标准

  1. 类整体描述

在头文件的开始处(前面没有任何doxygen注释)，格式如下:

/**
@brief The HelloWorld Scene.
注释 详细内容
*/

@brief 部分不是必须的，加入 @brief 可以在文档的最顶部加入简要的描述信息(The HelloWorld Scene.)，后面紧跟一个可以跳转到详细描述的超链接。

  1. 成员变量注释

在成员的上面一行，格式如下:

/** 注释内容 */

注意，文档中不会显示私有成员信息。public和protected成员都可以显示。

下面这种格式的注释，也可以。

int button; /**< "Run Again" button in GUI */
  1. 成员函数注释

在成员函数的上面一行，格式如下:

/**
@brief 描述
@param newNum 参数描述
@return "value" 返回值描述
*/
@brief同样为可选，可在文档的成员函数列表处做为简介显示。
@param参数描述
@return返回值描述

具体可以去Doxygen Manual查，有非常非常多的针对各语言的注释方法，按自己喜好使用。

  1. 大招来了

Mac上使用Doxygen自动生成脚本，高效完成doxygen风格注释。非常好用，非常便捷。

参考链接

* 安装ThisService.app，Mac上可自定义系统服务的工具软件。
* 下载Doxygen.rb脚本，它可以把文字输入转为doxygen风格注释输出。
* 打开ThisService，输入服务名称，选择执行的脚本，还有一些选项可以设置，比如指定服务生效的应用程序。 (我做了在编辑器中有效的设置)
* 在系统偏好设置->键盘中选择Service标签，找到刚刚添加的服务，为其设置一个快捷键如:Command+option+/。 完成，在XCode中选中一行代码，按快捷键试试效果吧。