常见问题

目录

• 如何在 HTML 的索引页上获取信息？
• 帮助，我的类/文件/命名空间的某些/所有成员没有文档？
• 当我将 EXTRACT_ALL 设置为 NO 时，文档中没有显示我的任何函数。
• 我的具有自定义扩展名的文件未被（正确）解析（或不再解析）。
• 如何让 Doxygen 忽略某些代码片段？
• 如何更改类文档中 #include 后面的内容？
• 如何结合压缩 HTML 使用标签文件？
• 我不喜欢放在每个 HTML 页面上方的快速索引，怎么办？
• 整体 HTML 输出看起来不同，而我只想使用自己的 html 头部文件
• 为什么 Doxygen 使用 Qt？
• 如何从我的目录树中排除所有测试目录？
• Doxygen 会自动在正文中的某个地方生成指向类 MyClass 的链接。如何阻止在特定位置生成链接？
• 我最喜欢的编程语言是 X。我还能使用 Doxygen 吗？
• 帮助！我收到神秘信息“input buffer overflow, can't enlarge buffer because scanner uses REJECT”
• 在 latex 目录中运行 make 时，我收到“TeX capacity exceeded”。现在怎么办？
• 为什么通过 STL 类的依赖关系没有显示在 dot 图中？
• 我遇到问题，无法让搜索引擎在 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 时，文档中没有显示我的任何函数。

为了记录全局函数、变量、枚举、typedef 和 define，您应该使用包含 \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

在应该隐藏的块周围，并将

如何更改类文档中 #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.cn/helpers.html）。
• 如果语法完全不同，可以为 X 编写一个解析器，并编写一个后端，生成与 src/scanner.l（以及读取标签文件时的 src/tagreader.cpp）类似的语法树。

帮助！我收到神秘信息“input buffer overflow, can't enlarge buffer because scanner uses 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 capacity exceeded”。现在怎么办？

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

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

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

我遇到问题，无法让搜索引擎在 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++，但它不够好（它不支持 signals and slots，也没有我喜欢的 Qt 外观），所以我开始编写自己的工具……

如何防止交错输出

重定向 Doxygen 的所有控制台输出（即消息和警告）时，输出可能会交错或顺序不符合预期。技术原因在于 stdout 可能会被缓冲。可以通过 Doxygen 的 -b 选项来克服此问题，例如 doxygen -b > out.txt 2>&1。请注意，这可能会花费更多一点时间。

前往下一部分或返回索引。