无法使用 Doxygen 记录头文件答案

【问题标题】：Unable to Document Header File with Doxygen无法使用 Doxygen 记录头文件
【发布时间】：2015-05-07 13:05:33
【问题描述】：

我正在尝试为仅包含一些常量的头文件生成文档，但我无法生成它。

按照doxygen manual 中的建议，我尝试将@file 关键字添加到评论块中，但仍然没有成功。

我错过了什么？

这是一个sn-p：

MyFile.h

 /**
 @file 
 my super important documentation.

 @author Julian Builes
*/
typedef NS_ENUM(NSUInteger, HTTPCode) 
{my code ...}

背景：这是一个使用 xcode 6 和 doxygen 1.8.9.1 的 iOS 项目

编辑：根据 Albert 的建议，我附上一个 sample project 来说明我遇到的问题。

【问题讨论】：

（编辑的）提供的代码对我来说确实适用于默认的 Doxyfile。从菲尔回答的评论中，不清楚问题是否得到解决。如果不是，请说明仍然出错的地方，doxygen 会报错吗？
@albert - 我仍然遇到问题。我没有让 doxygen 为不包含目标 c @class 指令的头文件生成任何文档。我还能尝试什么？
请创建一个小例子来显示包括 Doxyfile 在内的问题，并将其作为附件发布（最好还带有结果输出和控制台输出）在这里或 doxygen 用户邮件列表中（参见手册章节故障排除列表）
我在下面重写了我的答案。（我不确定我是应该这样做还是只是提供一个新的答案。）
如果您在预处理器指令中使用像 not 这样的 C++ 关键字，则不会记录标题的内容。此处提交的错误：github.com/doxygen/doxygen/issues/9172

标签： documentation doxygen documentation-generation

【解决方案1】：

我相信您的 Doxyfile 配置文件中有错误。只需将“INPUT =”行留空，doxygen 将在当前目录中搜索与您指定的模式匹配的源文件。当你改变它时，你应该在 doxygen 输出中看到

...
Parsing files
Preprocessing C:/temp/doxy test/TEDHTTPStatusCodes.h...
Parsing file C:/temp/doxy test/TEDHTTPStatusCodes.h...

您应该会在 doxygen 生成的主页上看到“文件”选项卡。

【讨论】：

谢谢菲尔！对不起，那是我的错字。我确实有额外的星号。已更新问题。
非常感谢！这似乎做到了。我没有为 INPUT 字段输入值。所以我想这是在设置一些其他值后自动填充的。为什么会这样？
Doxygen 可能找不到任何 INPUT 文件，因此只会生成并清空文档。在您的控制台输出中，您可能看不到任何正在处理的文件。很难猜测 INPUT = /Users/jlnbuiles/Desktop/test-doxy 来自何处，可能来自较早的测试并且您重新加载了 Doxyfile。
将 input= 留空意味着 doxygen 将搜索 current 目录。如果要搜索其他目录，则必须将路径放在这里。我尝试始终使用相对目录，以便配置文件可以在任何地方使用。至于不正确的绝对路径是从哪里来的，我猜是当你运行 doxywizard 时它就到了那里。我发现最好通读配置文件以确保它正在执行您想要的操作。这是有据可查的。祝你好运！

【解决方案2】：

“默认情况下，文件被视为私有文件。这意味着没有 @file 声明（或 \file）的文件将被忽略，并且不会包含在 Doxygen 输出中，C++ 类的成员除外。”
参考：https://linux.m2osw.com/doxygen-does-not-generate-documentation-my-c-functions-or-any-global-function

将以下内容放在标题顶部：

/**
 \file
*/

【讨论】：

OP 在他的文件中有@file 那么这怎么可能是答案？

【解决方案3】：

如果这有任何帮助（使用 v1.9.1），似乎@file (\file) 声明必须正好在左边距。我花了好几个小时想知道为什么一个特定的 .h 文件不起作用。

这样就OK了：

/**
@file
    @brief My superb interface
    @par Note re foo bar
Functions that output to the szFoo buffer use the throgglethorp algorithm.
*/

但这不是，@file 缩进

/**
    @file
    @brief Not so good
    @par Note re foo bar    
Functions that output to the szFoo buffer use the throgglethorp algorithm.
*/    

# Difference with default Doxyfile 1.9.1 (ef9b20ac7f8a8621fcfc299f8bd0b80422390f4b)
PROJECT_NAME           = MyProject
PROJECT_NUMBER         = 9.3.0
OUTPUT_DIRECTORY       = doxy
ABBREVIATE_BRIEF       =
FULL_PATH_NAMES        = NO
JAVADOC_AUTOBRIEF      = YES
QT_AUTOBRIEF           = YES
OPTIMIZE_OUTPUT_FOR_C  = YES
SHOW_INCLUDE_FILES     = NO
SORT_BRIEF_DOCS        = YES
SHOW_USED_FILES        = NO
SHOW_NAMESPACES        = NO
LAYOUT_FILE            = doxygen-layout.xml
INPUT                  = src/myIncludeFile.h
INPUT_ENCODING         = ISO-8859-1
FILE_PATTERNS          =
EXAMPLE_PATTERNS       =
VERBATIM_HEADERS       = NO
ALPHABETICAL_INDEX     = NO
HTML_FOOTER            = doxygen-footer.html
HTML_TIMESTAMP         = YES
MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
GENERATE_LATEX         = NO
LATEX_CMD_NAME         = latex
SEARCH_INCLUDES        = NO
DOT_FONTNAME           =

对于第二个实例（缩进 @file），结果是一个没有任何文档记录的 html 文件。在第一个实例中，我得到了我想要的结果，即带有副标题“myIncludeFile.h 文件参考”的 html/my_include_file_8h.html。

【讨论】：

你得到的输出是什么？出了什么问题？您的问题的可能原因可能是您的评论块以 4 个空格开头，这可能被视为逐字块的开头。
使用默认的 Doxyfile 时，两个实例的输出相同！因此，您的设置中的某些问题可能是问题，请澄清我们（使用doxygen -x Doxyfile 显示 Doxyfile 与默认版本相比的差异）。
我们不知道doxygen-footer.html 和doxygen-layout.xml 中的内容，但我认为它们的内容并不重要，因此在我的测试中我将它们排除在外。运行测试用例会在两种情况下给出相同、正确的结果。您的文件中是否有某个选项卡或行尾有空格？
我有 5 或 6 个项目，我使用完全相同的操作（仅为标记的 .h 文件制作 doc），并且多年来一直这样做没有问题。刚刚测试了另一个与 doxygen 1.8 及更早版本完美配合的项目。现在我已经更新到 v1.9，它给了我完全相同的问题，并且同样的修复工作。
仍然很奇怪，也许你应该在 doxygen github bug tracker 中创建一个问题。一个小小的怀疑是有一些警告被忽略了，或者源文件中有一些隐藏字符没有出现在堆栈上。（github 问题的标准文本：-您能否附上一个小的、自包含的示例（tar 或 zip 中的源+配置文件），以便我们重现问题？请不要添加外部链接，因为它们可能不要持久化。- 请同时指定使用的完整 doxygen 版本 (doxygen -v)。