doxygen教程-3-初探doxygen

终于开始正题啦, 下面开始介绍如何使用 doxygen. 首先要确定能在终端运行 doxygen, 如果不行的话, 请看上一篇教程.

(突然发现我的行文还是挺啰嗦的, 在正题之前, 居然能整出两篇长文…)

使用 doxygen 只需要做两件事

用好 doxygen , 说起来倒也简单, 就是做好两件事: 写配置文件和写注释. 学到后面就会发现, 我们一直在跟这两件事情打交道.

其实这里说"写注释"并不够全面, 实际上我们还可以写 markdown 文件等. 但是考虑到二者的性质是一样的, 而且后面主要介绍注释的语法, 所以这里就说 doxygen 主要涉及两个方面: 写配置和写注释.

Hello Doxygen

首先让我们新建一个文件夹, 命名为 hello_doxygen, 当作项目的根目录, 然后创建一个源文件 hello.c, 目录结构如下:

|--hello_doxygen\
   |--hello.c

然后在 hello.c 中输入以下内容:

/**@file hello.c */

/**
 * @brief   A hello func.
 * @details This hello function does nothing.
 */
void hello(){
    // do nothing
}

至此, 我们完成了第一件事: 写注释. 下面我们来完成第二件事.

编写配置文件并输出文档

配置文件记录了许多选项, 我们通过这些选项控制 doxygen 如何生成文档. 下面介绍编写配置文件的方法.

首先从地址栏复制项目目录的路径, 打开终端, 输入

cd /d <路径>

进入项目目录. 如图所示

如果命令行的开头变成了项目目录的路径, 说明切换成功. 然后输入命令

doxygen -g <文件名>

让 doxygen 为我们生成一个模板配置. 文件名也可以留空, 这样模板配置使用默认的文件名 Doxyfile, 如下图所示.

doxygen -g

于是, 我们的项目目录现在是这样的:

|--hello_doxygen\
   |--Doxyfile
   |--hello.c

最后, 输入

doxygen <配置文件名>

在这里, 也就是

doxygen Doxyfile

现在, 项目目录里应该多了两个文件夹, 变成这样:

|--hello_doxygen\
   |--html\
   |--latex\
   |--Doxyfile
   |--hello.c

这两个文件夹就是 doxygen 输出的文档. 进入 html 文件夹, 找到 index.html, 右键-打开方式, 用浏览器打开就可以看到 html 版的文档了.

依次点击 file-hello.c, 就可以看到我们之前写的注释变成文档显示在了网页上.

注意, 注释 // do nothing 并没有显示在文档中.

可以发现, 我们只用到了两句命令, 一个用来生成模板配置, 一个用来输出文档. 至此, 我们要用到的所有命令行都已经介绍完了 😃