what
doxygen是一个自动根据注释生成文档的工具。支持html、chm、pdf等格式。
安装
- 源码
github - 编译安装
工程使用cmake组织 。会缺少一些依赖，缺啥补啥就行。
生成文档的步骤
- 按照doxygen的规范进行代码注释
- 生成一个配置文件，根据自己的需要修改参数
- 调用doxygen生成文档
实验1：生成doxygen的文档。
- 准备源码
doxygen的代码本身就是按照自己的格式注释的，这里不需要操作。 - 生成配置文件
-doxygen –g - 生成不带注释的：
doxygen -s –g - 配置文件的修改参数
参数都有注释，可以简单修改一下类似工程名、语言这些基本配置，也可以不改。 - 进入源码目录，执行
doxygen your-cfg-filename
这就会生成一个html的文档。
image.png
这样就会生成一份doxygen自己的文档。
doxygen配置主要参数：
- PROJECT_NAME = “Test”
- PROJECT_NUMBER = 1.0.0
- OUTPUT_DIRECTORY = doc/
- OPTIMIZE_OUTPUT_FOR_C = NO
c++这里就用NO - TYPEDEF_HIDES_STRUCT = YES
定义的结构体、枚举、联合等数据类型，只按照 typedef定义的类型名进行文档化 - GENERATE_LATEX = NO
默认会生成一个html和latex的文档，有html就够了。 - RECURSIVE = YES
是否递归调用 - GENERATE TREEVIEW ＝ ALL
这会在HTML文档中，添加一个侧边栏，并以树状结构显示包、类、接口等的关系
注释规范
- 单行注释
用“//!”来表示，例如：//!概要 - 多行注释
/*!
xx@#$%~
xx^&*(
*/
- 各种标记
一些类似param、return这些标记，doxygen会解释这些标记。可以用@链接这些标记，也可以用\ -
b加粗 - param 参数
- tparam 模板参数
- code和encode用于表示一个代码块
SomeClass sc("hello");
string result;
int ret = sc.Func("world",3,result);
\endcode
- note 说明注释
- return 返回值
- todo 待做的
- deprecated 启用的
- 使用@分组
//! @name operator
//@{
bool operator==(const SomeClass& other) const { return true;}
bool operator!=(const SomeClass& other) const { return true;}
bool operator<(const SomeClass& other) const { return true;}
bool operator>(const SomeClass& other) const { return true;}
//@}
完整的示例：
- 代码：
#pragma once
/*! \file document.h */
#include <string>
#include <vector>
using namespace std;
//!概要
/*!
具体注释：
\tparam 模板参数的注释
\see SomeClass::SomeClass
这就是一个测试类。
\b "\b"表示加粗
\code
SomeClass sc("hello");
string result;
int ret = sc.Func("world",3,result);
\endcode
*/
template<typename Type>
class SomeClass
{
public:
/*!
构造函数
\param str 输入字符串
\note 说明
*/
SomeClass(string const& str){}
//! 函数注释概要
/*!
具体解释
\li 解释1
\li 解释2
\li 解释3
\param outStr 输出字符串
\return int 错误码,0表示成功
\todo 对各种错误进行整理
*/
int Func(string const& str,int len, string& outStr)
{
return 0;
}
//! \deprecated
int Func()
{
return 0;
}
//! @name operator
//@{
bool operator==(const SomeClass& other) const { return true;}
bool operator!=(const SomeClass& other) const { return true;}
bool operator<(const SomeClass& other) const { return true;}
bool operator>(const SomeClass& other) const { return true;}
//@}
public:
string value_;
private:
int len_;
Type type_;
}
-
生成的文档如下：
image.png
image.png
image.png
