Doxygen——根据代码注释生成文档的工具
文章目录
- 1 简介
- 2 安装
- 3 使用
-
- 3.1 注释代码
- 3.2 使用doxywizard生成文档
- 4 用例
-
- 4.1 OpenCV
- 4.2 Apollo
- 5 参考
1 简介
Doxygen是一个可以根据代码注释生成文档的工具，支持HTML、CHM、LaTex等格式。主要支持C语言、Python语言，还支持C++、Java、C#等语言。
通常我们在写程序时，或多或少都会写上注释，但是对于其它人而言，要直接探索程序里的注释会比较麻烦。大部分有用的注释都是属于对函数、类型等的说明。所以，如果能依据程序本身的结构，将注释经过处理重新整理成为一个纯粹的参考手册，对于后面利用此程序代码的人而言将会减少许多负担。
2 安装
sudo apt install doxygen
sudo apt install doxygen-gui
其中，doxygen使用命令行操作，doxygen-gui是doxygen的图形用户界面。
3 使用
3.1 注释代码
Doxygen能识别这几种风格的注释：
/**
* ... text ...
*/
/*!
* ... text ...
*/
///
/// ... text ...
///
//!
//!... text ...
//!
文件的开头必须有文件注释，否则该文件不会被识别：
/** @file */
结构化命令可以识别代码块的含义，主要包括：
\classto document a class.\structto document a C-struct.\unionto document a union.\enumto document an enumeration type.\fnto document a function.\varto document a variable or typedef or enum value.\defto document a #define.\typedefto document a type definition.\fileto document a file.\namespaceto document a namespace.\packageto document a Java package.\interfaceto document an IDL interface.@todothings to be done.
其中，\可以替换为@，即\class等价于@class。
具体怎么写注释？可以直接看一个使用Javadoc风格的C++代码文档的例子：
/**
* A test class. A more elaborate class description.
*/
class Javadoc_Test
{
public:
/**
* An enum.
* More detailed enum description.
*/
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar; /**< enum variable. Details. */
/**
* A constructor.
* A more elaborate description of the constructor.
*/
Javadoc_Test();
/**
* A destructor.
* A more elaborate description of the destructor.
*/
~Javadoc_Test();
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Javadoc_Test()
* @see ~Javadoc_Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
/**
* A pure virtual member.
* @see testMe()
* @param c1 the first argument.
* @param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
/**
* a public variable.
* Details.
*/
int publicVar;
/**
* a function variable.
* Details.
*/
int (*handler)(int a,int b);
};
单击此处查看由doxygen生成的相应HTML文档。
Doxygen也支持C和Python等编程语言的注释，用法可以参考此链接。
3.2 使用doxywizard生成文档
安装完成doxygen和doxygen-gui后，在终运行doxywizard命令启动Doxygen GUI。作为初学者，可以先使用Doxygen GUI熟悉doxygen的使用方法。
doxywizard的用法参考此链接，主要包括三个步骤：
- 设置
Wizard - 设置
Expert Run
Wizard页面包括：
- 设置项目，包括项目的名称，源代码路径和生成文档的路径
- 设置模式，更好地匹配编程语言
- 设置输出文件的格式
- 设置生成的图表
Expert页面包括很多高级的设置，要根据自己的实际需求调整。例如，我在注释Apollo项目中的类的私有成员函数时，输出的文档中并没有显示该信息，原因是没有选中Expert下Build中的EXTRACT_PRIVATE。
在Run页面点击Run doxygen按钮，窗口会输出日志信息，如果最后显示Doxygen has finished，则表明运行成功。
最后，点击Show HTML output，会使用浏览器打开将代码文档化的网页。
4 用例
4.1 OpenCV
OpenCV等开源库很好的使用了Doxygen，可以直接看文档和代码感受一下：
- https://docs.opencv.org/3.2.0/d2/d28/calib3d_8hpp.html
- https://github.com/opencv/opencv/blob/master/modules/calib3d/include/opencv2/calib3d.hpp
当然，OpenCV是一个优秀的开源库，内容多且详细，我们可以根据自己项目的实际情况制定一套规则。
4.2 Apollo
目前Apollo部分代码也使用了Doxygen，例如：
- https://github.com/ApolloAuto/apollo/blob/master/modules/common/math/kalman_filter.h
但是还没完全覆盖整个项目，Apollo 6.0计划推出在线的文档，大概率就是用这个工具生成的。
此外，Apollo的cyber模块更多的使用了doxygen。
cd /apollo/cyber/doxy-docs/
./build_doxy_sphinx.sh
安装相关依赖：
pip install sphinx breathe recommonmark -i https://pypi.tuna.tsinghua.edu.cn/simple
运行脚本：
./build_doxy_sphinx.sh
然后，打开/apollo/cyber/doxy-docs/build/html中任意一个html文件即可。
注：这种打开html文件的方法不是很优雅，因为我对doxygen的操作还不是很熟悉。
5 参考
- https://www.doxygen.nl/index.html
- https://docs.opencv.org/3.2.0/d2/d28/calib3d_8hpp.html
- https://github.com/opencv/opencv/blob/master/modules/calib3d/include/opencv2/calib3d.hpp
- https://github.com/ApolloAuto/apollo/blob/master/modules/common/math/kalman_filter.h
- https://baike.baidu.com/item/Doxygen/1366536?fr=aladdin