编程导航

学习目的

  doxygen是非常重要的代码阅读工具。按照一定的规范书写注释，能够快速帮助我们阅读代码。

语法

  参考这个【AXin带你学Doxygen 生成文档超简单！】视频学习基本语法。

  实体，是指函数、变量等对象。是我们要注释的对象。

  注释的格式有很多种。统一采用 C++ 的注释格式，比较熟悉方便。

1
/// 注释内容

为了方便阅读，不省略参数标志。

常用参数

brief

1
/// @brief 简要的描述

details

1
/// @details 详细的描述

see

  当函数名和其他函数名一致时，点击生成的 doxygen 网页能够实现实现跳转。

1
/// @see [函数名]

param

  当参数名和其他参数名一致时，生成的 doxygen 网页会高亮。

1
2
/// 函数注释
/// @param [参数名] 参数简述

return

  当变量名和其他变量名一致时，点击生成的 doxygen 网页能够实现实现跳转。

1
/// @return [变量名]

提示

  不同级别的提示。

1
2
3
/// @note 记录
/// @attention  注意
/// @warning 警告

在实体之后注释

1
2
///< 变量1注释
///< 变量2注释

源文件和头文件

  头文件存放了一些声明函数，起到接口作用。不同的源文件可能都会调用头文件里的函数，因此头文件具有一定的 “公共属性”。所以将简要的说明和必要的参数放在头文件。

1
2
3
/// @brief 函数注释
/// @param [参数名] 
/// @return [变量名]

  源文件中的函数是具体算法的实现，有时我们会更改算法，提示和说明就会产生变动。所以将详细的说明和提示放在源文件。

1
2
3
4
5
6
/// @details 详细的描述
/// @see [函数名]
/// @note 注释 
/// @attention 注意 
/// @warning 警告 
///< 变量1注释

生成方法

  用图形化界面生成。

工作目录

  存放项目配置文件。

Wizard：向导

  基础配置。包含源文件地址、是否递归（所有文件夹检索）、输出文件夹等。

工程

  一定要选择递归，检索所有子文件。

模式

  1. 一定要选择所有实体，要不然网页可能不会显示文件。
  2. 选择对应的编程语言。

输出

  可以选择关闭 LaTex 文件输出。

图表

  选择 GraphViz，打上所有勾，需要安装 GraphViz 软件，就能自动绘制函数和文件调用关系图。

Expert：专家

  高级配置。包含 Html 设置。是完包含 Wizard 中的设置，并大于 Wizard。

工程

  可以设置语言为中文。

Source Browser

  源码设置。

  1. SOURCE_BROWSER：显示实体函数所在位置，这个要勾选。
  2. INLINE_SOURCES；嵌入源码，不要勾选。太影响阅读了。

网页

  目录栏，横向换纵向：DISABLE_INDEX 和 GRNERATE_TREEVIEW 打勾。

Dot语言

  DOT语言是一种文本图形描述语言。我们用 GraphViz 软件。

DOT_PATH：dot.exe 文件的路径，在 GraphViz 软件安装的位置下的 bin 里。如果 GraphViz 已经添加了全局变量，这个就不用设置。

Run：运行

  运行和跳转网页。