什么是 doxygen
doxygen 是一款为 C++ 代码生成文档的工具. 只要按照 doxygen 的语法编写注释, doxygen 就可以从源码中提取出这些注释, 并生成文档. 如果源码中没有符合 doxygen 语法的注释, doxygen 也可以在其生成的文档中展示代码的结构, 如调用关系图, 继承图等. 如此, 就可以使得文档始终与代码保持一致.
opencv 的在线文档 就是用doxygen 生成的, 如下图
doxygen 的语法很简单, 例如下面代码的注释可以生成下图的文档:
/**
* @brief 整型加法函数.
* @details 传入两个整型参数, 返回值为两个整数相加的结果.
*/
int add(int a, int b) {}
除了通过提取注释生成文档, 也可以直接编写文档. doxygen 在语法上支持标题, 表格, 链接等结构, 这些结构构成了一篇文章. 将所有内容都放到代码的注释中并不是很合理, 例如安装说明, 使用教程等文章. 将这些内容直接编写成文档更加合适. doxygen 支持 markdown, 因此可以用 markdown 的语法来代替 doxygen 的语法. 考虑到 github, gitee 的普及程度, 以及 typora 编辑 markdown 的舒适程度, 个人更喜欢用 markdown 来编写文档.
doxygen 支持的语言列表很长, 如Python, PHP, C#等. 在 C++ 中, doxygen是事实上的标准, 但在其他的语言中, doxygen不见得是最好的选择, 例如Python可能就更适合sphinx(很多库的readthedoc都能看到sphinx的名字).
doxygen 支持多种输出格式, 如 HTML, LaTex, RTF, PDF 等.
关于本教程
本套教程的内容主要基于 doxygen 的官方手册, 一定程度上可以看作是官方手册的节选和翻译.
在阅读手册的过程中, 我写了一些 demo 来加深理解, 这些内容整理之后就形成了现在这套教程, 所以也可以将其看作是我的学习笔记. 现在网上已经有很多 doxygen 教程, 我最初也受教于这些文章. 这套教程实际上是我从方方面面所学知识的整合. 如果你更喜欢直接阅读官方手册的话, 那么现在可以退出本文了, 你不会遗失任何有用的信息.
出于工作需要, 本教程侧重于以下几点:
- 侧重于 C 语言, 因为部门的核心语言是 C 语言.
- 由于公司电脑的信息安全限制, 安装程序会被拦截, 所以只能使用免安装的软件. 因此本教程侧重于以命令行的方式运行 doxygen.
- 只讨论 HTML 格式的输出. 本来也想输出PDF的, 但是要安装 LaTex, 在公司电脑上折腾了一下, 都被拦截了, 于是作罢.
本教程使用的 doxygen 版本是 1.9.2.
see also
其他教程
如上所述, 还存在许多其他学习 doxygen 的资源, 这里给出一些参考.
-
AXin带你学Doxygen 生成文档超简单！https://www.bilibili.com/video/BV1ZE411F7kW
入门视频, 介绍了 Windows 和 Linux 下的安装, 图形界面的使用, 以及如何编写注释等.
-
介绍 doxygen 的安装, 以及在命令行下的用法.
-
介绍了 doxygen 的常见语法.
官方手册
最权威, 一手的资料, 深入了解 doxygen 的必读文档.