如何用doxygen生成文档

Doxygen是一款基于源代码生成文档的工具,类似于Java中的javadoc.

概念:文档和注释的区别

文档(Documentation)

是给代码的使用者准备的,或者是更高一级的开发者或者是用户,主要是告诉使用者如何更好的使用代码.典型例子就是API文档.

注释

代码的一部分,解释代码为什么这样写,是给代码的维护者准备的.
优秀且可读的代码应该不需要注释,但文档应该是必须有的,特别是API文档.

在代码中加入文档

这个是第一步,也是最重要的一步,直接影响着文档的优与劣.
Doxygen是一个比较成熟的工具了,它有非常详细且专业的文档.
文档是写在代码当中的,以注释块的形式,为了区分代码中的正常注释,访文档需要用特殊的形式的注释块来呈现.Doxygen支持多种文档注释块:

• Javadoc形式的:

/**
  * ...
  */

• QT形式的

/*!
  * ...
  */

• 或者,这样

///
/// ...
///

• 或者,这样

//!
//! ..
//!

后二种有点非主流,不建议使用.推荐使用前面二种.当然,配置了某些特殊的选项也可以使用其他格式.
当Doxygen看到这种形式的注释块时就会把它从代码中抽取出来,生成HTML形式的文档.
为了让文档更且有可读性,表达出更多的信息,Doxygen就定义了很多的命令,常用的有:

• \file  告诉Doxygen这是某个文件的文档块
• \enum 给一个enum类型加文档
• \struct 给一个结构体加文档
• \param 函数的参数
• \return  函数的返回值
• \see  交叉参考
• \brief  简介,用于概览时控制在一行以内,可以空一行,然后写更多的详细的内容
• \code \endcode 示例代码
• \note 注意事项
• \par HTML中的<p>

需要注意的是,这些命令也可以用javadoc格式的来写如@file, @enum, @return等.但建议用标准格式,因为\只需要敲一下,而@需要敲二下,另外就是并不是所有的命令都支持javadoc格式.

还有就是如果想写交叉引用可以在前面加个#就会自动转为相应的链接,直接上个例子就都明白了:

/**
 * \brief Obtain current list of path 
 *
 * \param [out] paths a pointer to an array of strings
 * \param [out] count indicating the count of path.
 *
 * \note
 * This function will allocate memory for path array. So caller must free the array, but should not free each item.
 *
 * \return #API_RESULT_CODE indicating whether this call success or failed.
 *
 * \par Sample code:
 * \code
 *    char **path = NULL;
 *    int count = 0;
 *    test_get_paths(&path, &count);
 *    // use the path
 *    free(path);
 *    path = NULL;
 * \endcode
 */
int test_get_paths(char ***paths, int *count);

配置Doxygen

Doxygen需要一个配置文件来告诉Doxygen一些选项.配置文件就是一个纯文本文件,格式跟标准的Linux配置文件一样:一行一个配置项,前面是配置项的名字,然后是等号后面就是配置项的值了.以#开头都是注释.Doxygen的选项特别的多,不可以手动的去写,通常都是编辑一个现有的模板,这个模板可以用Doxygen来生成:
doxygen -g config-filename
config-filename就是生成的配置文件模板,每个配置项前面都有一大段文档详细说明用途以及如何修改.绝大多数配置项是不需要修改的,仅有一些常用的需要修改:

• PROJECT_NAME   项目的名字,一定要改成你项目的名字
• PROJECT_NUMBER 编号,通常使用项目的版本号
• OUTPUT_DIRECTORY 文档输出存放目录,建议修改,比如doc
• PROJECT_BRIEF 项目的描述,会出现文档每一页的上面,控制在一行80字符内(越短越好)
• EXTRACT_*** 打头的选项要仔细读,如果是API文档,则这些全都要设成NO,这样就仅抽取特定文档块内的内容.

其他的选项都可以不改,用默认的就成.

生成文档

这步最简单,如果前面都就绪了,仅需要运行命令即可:
doxygen config-filename
后,文档就会出现在所指定的输出目录中.

doxygen会打印出日志信息.为了保证质量,最好把把的Warning都修正掉.(这跟修正代码的所有编译警告一个道理).

上面例子生成的文档:

int test_get_paths	(	char ***	paths,
		int *	count
	)

Obtain current list of path.

Parameters:

[out]	paths	a pointer to an array of strings
[out]	count	indicating the count of path.

Note:

This function will allocate memory for path array. So caller must free the array, but should not free each item.

Returns:

API_RESULT_CODE indicating whether this call success or failed.

Sample code:

    char **path = NULL;
    int count = 0;
    test_get_paths(&path, &count);
    // use the path
    free(path);
    path = NULL;

完整示例下载