如何用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>
还有就是如果想写交叉引用可以在前面加个#就会自动转为相应的链接,直接上个例子就都明白了:
/**
* \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;
完整示例下载