doxygen 的使用

前期准备

简介

doxygen是一个跨平台跨语言的代码文档化工具

下载

http://www.stack.nl/~dimitri/doxygen/

编译安装

这个软件没有甚么特殊的配置，默认安装位置是 /usr/local

./configure
make
make install

如上就搞定了

准备配置文件

doxygen -g <configure_name>

通过上面的命令可以生成一个按照系统模板输出的配置文件，每一个代码集需要一个独立的配置文件

配置文件

网上很多都是如何通过UI来控制配置文件，可惜我们只能远程处理设备，所以只能采用命令行的方式处理，看上去配置文件很大很复杂，其实需要修改的地方并不多。

我们的项目是基于C代码的，并且只需要HTML的web帮助方式，只需要做如下的设定，其他全部采用默认值。

项目设定

PROJECT_NAME	项目的名称（可以直接使用UTF-8中文，配置文件中所有的地方一样）
PROJECT_NUMBER	项目的版本号
OUTPUT_DIRECTORY	最终输出的文档位置
OUTPUT_LANGUAGE	输出的文档语言，可以直接设置为 Chinese
INPUT	代码放置的位置，若分开不同的目录，可以用空格分隔开
FILE_PATTERNS	处理的文件后缀，可以设定 .c .h 一样多个参数用空格分隔开
GENERATE_LATEX	是否输出 LATEX 格式文档，默认是 YES，我们不需要设定为 NO
RECURSIVE	是否在指定目录搜索所有的子目录

输出控制

OPTIMIZE_OUTPUT_FOR_C	是否生成符合 C 代码习惯的文档，设定 YES
TYPEDEF_HIDES_STRUCT	使用 typedef 定义相关内容，打开这个选项
EXTRACT_ALL	是否输出所有的函数、方法，忽略内部函数和私有方法等内容

HTML 输出

TOC_EXPAND 是否在索引中列举成员名称和分组信息

其他参数

这里有一个连接可以查看更多的配置参数说明内容： http://blog.csdn.net/yongshengfree/article/details/4533428

代码中的注释

文件注释

/**
 * @file xxxx.h
 * @brief 我是干神马滴
 * @brief 详细说明我是干神马滴
 * @author 谁搞了我
 * @date 啥时候搞了我
 */

常量、变量、成员等的说明

int result ///< 我是放结果的地方

这里需要注意，doxygen默认所有的注释都是说明下面的内容的，若要说明前面的内容要使用 ///< 开头

函数说明

/**
 * @brief 我是干神马滴
 * @details 详细说明我是干神马滴
 * @param[in] XXX 这个输入的参数是干神马滴
 * @param[out] XXX 这个输出参数时干神马滴
 * @param[in,out] XXX 这个又输入又输出
 * @retval !NULL 这种返回值是啥意思
 * @retval NULl 这种返回值又是啥意思
 * @return 返回值是干神马滴
 */

经常使用的还有

@warning 这里需要特别注意什么

@see 可以去参考一个什么

@deprecated 这个东西已经取消了，会在取消列表中被显示出来

其他说明

其他的可以去参考doxygen的相关说明

常用的就有一个 @todo ，这个东西在编写时随时可以添加，记录BUG和编程思路很有用处，在最终的文档中会单独有一个页面列出所有的 TODO 的相关内容和函数、文件位置

参考文件：

• http://madmanahong.blog.163.com/blog/static/488509620089842454971/
  
• http://blog.csdn.net/wangxvfeng101/article/details/7301115