如何使用doxygen生成代码文档

如何使用doxygen生成代码文档

public class CloudLed {
boolean m_isOn;
Camera m_Camera;
public boolean getIsOn() { return m_isOn; }
public CloudLed()
{
m_isOn = false;
}
public void turnOn()
{
if(!m_isOn)
{
m_isOn = true;
try
{

在代码中加入文档 这个是第一步,也是最重要的一步,直接影响着文档的优与劣. doxygen是一个比较成熟的工具了,它有非常详细且专业的文档. 文档是写在代码当中的,以注释块的形式,为了区分代码中的正常注释,访文档需要用特殊的形式的注释块来呈现.doxygen支持多种文档注释块: javadoc形式的:qt形式的或者,这样/// /// ... ///或者,这样//! //! .. //!后二种有点非主流,不建议使用.推荐使用前面二种.当然,配置了某些特殊的选项也可以使用其他格式. 当doxygen看到这种形式的注释块时就会把它从代码中抽取出来,生成html形式的文档. 为了让文档更且有可读性,表达出更多的信息,doxygen就定义了很多的命令,常用的有: \file 告诉doxygen这是某个文件的文档块\enum 给一个enum类型加文档\struct 给一个结构体加文档\param 函数的参数\return 函数的返回值\see 交叉参考\brief 简介,用于概览时控制在一行以内,可以空一行,然后写更多的详细的内容\code \endcode 示例代码\note 注意事项\par html中的 需要注意的是,这些命令也可以用javadoc格式的来写如@file, @enum, @return等.但建议用标准格式,因为\只需要敲一下,而@需要敲二下,另外就是并不是所有的命令都支持javadoc格式. 还有就是如果想写交叉引用可以在前面加个#就会自动转为相应的链接,直接上个例子就都明白了: int test_get_paths(char ***paths, int *count);配置doxygen doxygen需要一个配置文件来告诉doxygen一些选项.配置文件就是一个纯文本文件,格式跟标准的linux配置文件一样:一行一个配置项,前面是配置项的名字,然后是等号后面就是配置项的值了.以#开头都是注释.doxygen的选项特别的多,不可以手动的去写,通常都是编辑一个现有的模板,这个模板可以用doxygen来生成: doxygen -g 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; 完整示例下载