Doxygen 简介

1. Doxygen 是什么

Doxygen 是一个程序文档生成工具，可以将代码中的注释转换成说明文档（API 参考手册），从而减少程序员手工整理文档的时间。

前提是：代码注释需要遵循 Doxygen 的规则书写，才能被正确识别和转换。

2. 支持的语言与输出格式

2.1 可处理的语言

  • C/C++
  • Java
  • Objective-C
  • IDL
  • 等

2.2 可生成的文档格式

  • HTML
  • XML
  • LaTeX
  • RTF
  • 等

2.3 常见衍生输出

  • HTML 可以打包成 CHM
  • LaTeX 可以借助工具生成 PS / PDF

3. 安装（Windows）

3.1 安装列表与下载地址

4. 常用配置项说明

4.1 提取范围（是否把这些成员输出到文档里）

  • EXTRACT_ALL
    • 输出所有函数，但 private 和 static 函数不属于其管制。
  • EXTRACT_PRIVATE
    • 输出 private 函数。
  • EXTRACT_STATIC
    • 输出 static 函数。

4.2 隐藏未写注释的成员

  • HIDE_UNDOC_MEMBERS
    • 没有使用 doxygen 格式描述的对象（函数/类等）不显示。
    • 注意：如果启用了 EXTRACT_ALL，这个标志会被忽略。

4.3 内部文档（@internal）

  • INTERNAL_DOCS
    • 是否输出注释中的 @internal 部分。
    • 若未启用：所有 @internal 内容在目标帮助中不可见。

4.4 命名与作用域显示

  • CASE_SENSE_NAMES
    • 是否关注大小写名称。开启后所有名称将被小写。建议对 C/C++ 永远不要开启。
  • HIDE_SCOPE_NAMES
    • 域隐藏。建议永远不要开启。

4.5 include / 文件列表相关页面

  • SHOW_INCLUDE_FILES
    • 是否显示包含文件。开启后会专门生成一个页面包含所有包含文件的列表。
  • SHOW_USED_FILES
    • 是否在函数/类的帮助中最下面显示来源文件。
  • SHOW_FILES
    • 是否显示文件列表页面。

4.6 显示细节与排序

  • INLINE_INFO
    • 开启后：文档里 inline 函数前会带一个 inline 修饰词标明。
  • SORT_MEMBER_DOCS
    • 开启后：文档成员列表按函数名称排序。
    • 否则：按解释出现的顺序显示。

4.7 TODO 列表

  • GENERATE_TODOLIST
    • 是否生成 TODOLIST 页面。
    • 开启后：@todo 注解内容会单独生成并显示在一个页面中。