常见问题解答

目录

• 如何在 HTML 中的索引页面上获取信息？
• 帮助，我的类/文件/命名空间的一些/所有成员都没有被记录？
• 当我将 EXTRACT_ALL 设置为 NO 时，我的所有函数都不会显示在文档中。
• 我的带有自定义扩展名的文件（不再）被正确解析。
• 如何使 Doxygen 忽略某些代码片段？
• 如何更改类文档中 \#include 之后的内容？
• 如何将标签文件与压缩 HTML 结合使用？
• 我不喜欢每个 HTML 页面上方显示的快速索引，我该怎么办？
• 整体 HTML 输出看起来不同，而我只想使用我自己的 html 标题文件
• 为什么 Doxygen 使用 Qt？
• 如何从我的目录树中排除所有测试目录？
• Doxygen 在运行文本中的某个位置自动生成指向类 MyClass 的链接。如何在特定位置阻止这种情况？
• 我最喜欢的编程语言是 X。我还可以使用 Doxygen 吗？
• 救命！我收到神秘的消息“输入缓冲区溢出，因为扫描器使用 REJECT，无法扩大缓冲区”
• 在 latex 目录中运行 make 时，我得到“TeX 容量超出”。现在怎么办？
• 为什么通过 STL 类的依赖关系没有显示在点图中？
• 我在使用 PHP5 和/或 Windows 时遇到了搜索引擎无法工作的问题
• 我可以从命令行配置 Doxygen 吗？
• Doxygen 是如何得名的？
• 开发 Doxygen 的原因是什么？
• 如何防止交错输出

如何在 HTML 中的索引页面上获取信息？

您应该在类似这样的注释块中使用 \mainpage 命令

/*! \mainpage My Personal Index Page
 *
 * \section intro_sec Introduction
 *
 * This is the introduction.
 *
 * \section install_sec Installation
 *
 * \subsection step1 Step 1: Opening the box
 *
 * etc...
 */

帮助，我的类/文件/命名空间的一些/所有成员都没有被记录？

请检查以下内容

1. 你的类/文件/命名空间是否被记录？如果没有，它将不会从源代码中提取，除非在配置文件中将 EXTRACT_ALL 设置为 YES。
2. 成员是私有的吗？如果是，则必须将 EXTRACT_PRIVATE 设置为 YES 才能使其出现在文档中。

3. 你的类中是否存在不以分号结尾的函数宏（例如 MY_MACRO()）？如果是这样，则必须指示 Doxygen 的预处理器将其删除。

   这通常归结为配置文件中的以下设置

   ENABLE_PREPROCESSING   = YES
   MACRO_EXPANSION        = YES
   EXPAND_ONLY_PREDEF     = YES
   PREDEFINED             = MY_MACRO()=
   

   请阅读手册的预处理部分以获取更多信息。

当我将 EXTRACT_ALL 设置为 NO 时，我的所有函数都不会显示在文档中。

为了记录全局函数、变量、枚举、类型定义和宏定义，您应该使用包含 \file（或 @file）命令的注释块来记录这些命令所在的文件。

或者，您可以使用 \ingroup 命令将所有成员放入组（或主题）中，然后使用包含 \defgroup 命令的注释块来记录该组。

对于成员函数或属于命名空间的函数，您应该记录类或命名空间。

我的带有自定义扩展名的文件（不再）被正确解析。

Doxygen 仅解析指定为输入（通过 INPUT 标签）并匹配指定扩展名（在 FILE_PATTERNS 中提到）的文件。然后，通过排除列为 EXCLUDE 的文件或与 EXCLUDE_PATTERNS 设置的模式匹配的文件来减少文件列表。

过去，Doxygen 将所有具有未知扩展名的文件解析为 C 文件，这可能会导致不希望的结果。自 1.8.8 版本起，Doxygen 要求您指定一个映射，该映射会告知对于特定的文件扩展名，应使用哪个解析器。此映射使用 EXTENSION_MAPPING 标签指定。如果未指定映射，则会忽略该文件的内容。

如何使 Doxygen 忽略某些代码片段？

新的、最简单的方法是在要忽略的代码片段的开头添加一个带有 \cond 命令的注释块，并在结尾添加一个带有 \endcond 命令的注释块。当然，这应该在同一文件中。

但是您也可以为此使用 Doxygen 的预处理器：如果您放置

#ifndef DOXYGEN_SHOULD_SKIP_THIS

 /* code that must be skipped by Doxygen */

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

在应隐藏的块周围并放置

  PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS

在配置文件中，则只要将 ENABLE_PREPROCESSING 设置为 YES，Doxygen 就会跳过所有块。

如何更改类文档中 #include 之后的内容？

在大多数情况下，您可以使用 STRIP_FROM_INC_PATH 来剥离路径的用户定义部分。

您也可以按如下方式记录您的类

/*! \class MyClassName include.h path/include.h
 *
 *  Docs for MyClassName
 */

为了让 Doxygen 放置

#include <path/include.h>

在类 MyClassName 的文档中，而不管实际包含 MyClassName 定义的头文件的名称是什么。

如果您希望 Doxygen 显示应使用引号而不是尖括号包含包含文件，则应键入

/*! \class MyClassName myhdr.h "path/myhdr.h"
 *
 *  Docs for MyClassName
 */

如何将标签文件与压缩 HTML 结合使用？

如果要从一个压缩 HTML 文件 a.chm 引用另一个名为 b.chm 的压缩 HTML 文件，则 a.chm 中的链接必须具有以下格式

<a href="mk:@MSITStore:b.chm::/file.html">

不幸的是，只有当两个压缩 HTML 文件位于同一目录中时，此方法才有效。

因此，您必须将所有项目的生成的 index.chm 文件重命名为唯一的文件名，并将所有 .chm 文件放在一个目录中。

假设您有一个项目a，它使用标签文件 b.tag 引用项目b，那么您可以将项目a的 index.chm 重命名为 a.chm，并将项目b的 index.chm 重命名为 b.chm。在项目a的配置文件中，您写入

TAGFILES = b.tag=mk:@MSITStore:b.chm::

我不喜欢每个 HTML 页面上方显示的快速索引，我该怎么办？

您可以通过将 DISABLE_INDEX 设置为 YES 来禁用索引。然后，您可以通过编写自己的标头并将其馈送到 HTML_HEADER 来放入自己的标头文件。

整体 HTML 输出看起来不同，而我只想使用我自己的 html 标题文件

您可能忘记包含 Doxygen 生成的样式表 doxygen.css。您可以通过放置

<LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">

在 HTML 页面的 HEAD 部分中来包含此内容。

为什么 Doxygen 使用 Qt？

在过去（1.9.2 版本之前），Doxygen 使用 Qt 2.x 的一部分来处理各种实用程序类。这些已经被 STL 容器类所取代。

名为 Doxywizard 的 GUI 前端基于现代版本的 Qt。Doxygen 本身也可以在没有 GUI 的情况下使用。

如何从我的目录树中排除所有测试目录？

只需在配置文件中放入如下排除模式

EXCLUDE_PATTERNS = */test/*

Doxygen 在运行文本中的某个位置自动生成指向类 MyClass 的链接。如何在特定位置阻止这种情况？

在类名称前面放置一个 %。像这样：%MyClass。然后，Doxygen 将删除 % 并使该词保持未链接状态。

我最喜欢的编程语言是 X。我还可以使用 Doxygen 吗？

不能，不能直接使用；Doxygen 需要理解它读取的内容的结构。如果您不介意花费一些时间，那么有几种选择

• 如果 X 的语法接近 C 或 C++，那么稍微调整一下 src/scanner.l 以便支持该语言可能并不太难。对于 Doxygen 直接支持的所有其他语言（即 Java、IDL、C#、PHP），都是这样做的。
• 如果 X 的语法有些不同，则可以编写一个输入过滤器，将 X 转换为与 C/C++ 足够相似的内容，以便 Doxygen 理解（这种方法用于 VB、Object Pascal 和 JavaScript，请参阅 https://doxygen.cpp.org.cn/helpers.html）。
• 如果语法完全不同，则可以为 X 编写一个解析器，并编写一个后端来生成与 src/scanner.l（以及读取标签文件时 src/tagreader.cpp）所做的类似的语法树。

救命！我收到神秘的消息“输入缓冲区溢出，因为扫描器使用 REJECT，无法扩大缓冲区”

当 Doxygen 的词法扫描器具有一次匹配超过 256K 个输入字符的规则时，会发生此错误。我曾在非常大的生成文件（>256K 行）上看到过这种情况，其中内置的预处理器将其转换为一个空文件（包含 >256K 个换行符）。如果您的代码行中有超过 256K 个字符，则可能会发生另一种情况。

如果您遇到这种情况并希望我修复它，则应向我发送触发该消息的代码片段。要解决此问题，请在文件中添加一些换行符，将其拆分为较小的部分，或使用 EXCLUDE 将其从输入中排除。

解决此问题的另一种方法是将 cmake 命令与选项一起使用

-Denlarge_lex_buffers=<size>

其中 <size> 是输入 (YY_BUF_SIZE) 和读取 (YY_READ_BUF_SIZE) 缓冲区的新大小。如果未给出此选项，则将使用默认值 262144（即 256K）。

在 latex 目录中运行 make 时，我得到“TeX 容量超出”。现在怎么办？

您可以编辑 texmf.cfg 文件以增加各种缓冲区的默认值，然后运行“texconfig init”。

为什么通过 STL 类的依赖关系没有显示在点图中？

除非启用选项 BUILTIN_STL_SUPPORT，否则 Doxygen 不知道 STL 类。

我在使用 PHP5 和/或 Windows 时遇到了搜索引擎无法工作的问题

请阅读此文档以获取有关在哪里查找的提示。

我可以从命令行配置 Doxygen 吗？

不是通过命令行选项，但是 Doxygen 可以从 stdin 读取，所以你可以通过管道传输内容。这里有一个例子，展示了如何从命令行覆盖配置文件中的选项（假设是类 UNIX 环境）

( cat Doxyfile ; echo "PROJECT_NUMBER=1.0" ) | doxygen -

对于 Windows 命令行，以下操作将达到相同的效果

( type Doxyfile & echo PROJECT_NUMBER=1.0 ) | doxygen.exe -

对于 Windows Powershell (使用 5.1 版本测试过)，以下操作将达到相同的效果

&{ type Doxyfile ; echo "PROJECT_NUMBER=1.0" } | doxygen -

如果指定了多个同名选项，Doxygen 将使用最后一个。要追加到现有选项，可以使用 += 运算符。

Doxygen 这个名字是怎么来的？

Doxygen 这个名字来源于对文档（documentation）和生成器（generator）这两个词的组合。

documentation -> docs -> dox
generator -> gen

当时我在研究 lex 和 yacc，很多东西都以 "yy" 开头，所以 "y" 被加入进来，使发音更顺畅（正确的发音是 Docs-ee-gen，"e" 是长音）。

开发 Doxygen 的原因是什么？

我曾经基于 Qt 库编写了一个 GUI 小部件（它仍然可以在 https://sourceforge.net/projects/qdbttabular/ 上找到，但自 2002 年以来就没有更新过）。Qt 有很好的文档生成工具（使用了一个内部工具，他们不想发布），我手动编写了类似的文档。这使得维护工作成为一场噩梦，所以我想要一个类似的工具。我看过 Doc++，但它不够好（它不支持信号和槽，也没有我习惯的 Qt 外观和感觉），所以我开始编写自己的工具...

如何防止交错输出

当重定向 Doxygen 的所有控制台输出（即消息和警告）时，可能会出现交错或顺序错乱的情况。其技术原因是 stdout 可以被缓冲。可以通过 Doxygen 的 -b 选项来解决这个问题，例如 doxygen -b > out.txt 2>&1。请注意，这可能会花费更多时间。

转到下一节或返回索引。