【C&C++】Doxygen - C++项目的文档生成工具

背景

在进行Amazon AVS C++ SDK的深度开发和学习时候经常会看到Amazon AVS官方的API说明文档，第一感觉是就是一个字***“好”***

Amazon AVS C++ SDK 官方的API说明文档部分截图,

在初步调研后，该文档是通过doxygen这一工具进行生成的.

所以希望能通过这篇文章能让更多的人开始基于doxygen进行C/C++代码的API说明文档的自动生成.

doxygen官网链接

另外本文接下来所给出的例子都是基于Ubuntu 20.4下的.

doxygen 的安装和常用命令介绍

doxygen 的安装

在这里我是直接命令行doxygen的安装，
直接使用apt-get install命令进行安装

sudo apt-get install doxygen

在成功安装后，运行doxygen -v进行版本确认. 我这里用的是1.8.13

➜  test doxygen -v
1.8.13
➜  test 

常用命令介绍

 doxygen -g  //自动生成doxygen配置文件Doxyfile
 doxygen configName //configName需要包含文件路径

默认情况执行doxygen -g 会报错，

sh: dot: not found

需要安装graphviz命令，这是因为doxygen依赖graphviz进行绘图.

sudo apt-get install graphviz

如何使用doxygen进行document的生成

运行 doxygen -g

在执行doxygen -g后，该目录下会自动生成doxygen配置文件Doxyfile.
Doxyfile就是doxygen 所遵循的配置文件.
然后需要对配置文件进行一些修改,

INPUT   = or += 需要进行生成Doc的源文件路径

RECURSIVE 需要配置为 YES，代表需要进行子目录的搜索

OUTPUT_DIRECTORY  配置输出的目录

EXTRACT_ALL = yes
EXTRACT_PRIVATE = yes
EXTRACT_STATIC = yes

# USE_MDFILE_AS_MAINPAGE  添加MainPage的内容，可以使Markdown格式文件

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

最后在Doxyfile文件所在的目录运行doxygen ./Doxyfile

➜  Embedded-Linux-Utils-Library git:(master) ✗ doxygen ./Doxyfile 
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for msc files...
Searching for dia files...
...

然后会在OUTPUT_DIRECTORY 所指定的目录输出document的相关文件

➜  Embedded-Linux-Utils-Library git:(master) ✗ ls /tmp/docs/     
html  latex

最后通过浏览器打开html下的index.html这一文件, 进行API文件的阅读.

示例演示

接下来会基于Ubuntu 演示下Doxygen的使用.
在D-Bus C++ Client实现后，基于该代码仓库输出本示例