如何用doxygen生成文档

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

概念:文档和注释的区别文档(Documentation)是给代码的使用者准备的,或者是更高一级的开发者或者是用户,主要是告诉使用者如何更好的使用代码.典型例子就是API文档.
注释代码的一部分,解释代码为什么这样写,是给代码的维护者准备的.
优秀且可读的代码应该不需要注释,但文档应该是必须有的,特别是API文档.
在代码中加入文档这个是第一步,也是最重要的一步,直接影响着文档的优与劣.
Doxygen是一个比较成熟的工具了,它有非常详细且专业的文档.
文档是写在代码当中的,以注释块的形式,为了区分代码中的正常注释,访文档需要用特殊的形式的注释块来呈现.Doxygen支持多种文档注释块:
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);

配置DoxygenDoxygen需要一个配置文件来告诉Doxygen一些选项.配置文件就是一个纯文本文件,格式跟标准的Linux配置文件一样:一行一个配置项,前面是配置项的名字,然后是等号后面就是配置项的值了.以#开头都是注释.Doxygen的选项特别的多,不可以手动的去写,通常都是编辑一个现有的模板,这个模板可以用Doxygen来生成:
doxygen -g config-filename
config-filename就是生成的配置文件模板,每个配置项前面都有一大段文档详细说明用途以及如何修改.绝大多数配置项是不需要修改的,仅有一些常用的需要修改:
PROJECT_NAME 项目的名字,一定要改成你项目的名字PROJECT_NUMBER 编号,通常使用项目的版本号OUTPUT_DIRECTORY 文档输出存放目录,建议修改,比如docPROJECT_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]pathsa pointer to an array of strings[out]countindicating 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;

完整示例下载