在Doxygen中使用Microsoft的源代码注释语言（SAL）？

Question

我正在尝试使用Doxygen记录一些使用Microsoft的源代码注释语言（SAL）的 C ++代码。 但是，Doxygen无法正确解析某些注释宏，例如_Success_ 。 在示例函数注释 _Success_的情况下，Doxygen将此宏误解为函数标头/原型。

请看以下包含函数注释标记的示例：

/**
 *    @file
 *    Example with function annotation.
 */

#include <windows.h>
#include <sal.h>

/**
 *    @brief This is a function.
 *    @param i a random variable
 *    @return TRUE on every call.
 */
_Success_(return) // The SAL function annotation.
BOOL function(_In_ int i) {
    return TRUE;
}

在上面的示例中，Doxygen将_Success_()解释为函数头/原型，从而创建了绝对错误的文档。 这是带有和不 带有 功能注释的HTML Doxygen输出的外观：

通过函数注释 ，Doxygen还说我记录了一个不属于参数列表的参数变量i ：

C：/.../ Source.cpp：9：警告：在成功 （返回）的参数列表中找不到命令@param的参数'i'

我是否在Doxygen主配置文件中缺少配置设置？
还是SAL和Doxygen只是不兼容？

Answer 1

啊哈！ 经过一番研究的深入，我发现了一个问题上堆栈溢出是问同样的问题，但它没有被正确标记，并没有明确地说他/她是使用“微软的SAL。” 这就是为什么我花了一段时间才找到它的原因。 （我已经更新了相应的问题来纠正这些错误步骤。）

问题的答案参考了Doxygen手册的标题为： 预处理 。

一个典型的需要预处理器帮助的示例是在处理Microsoft的语言扩展时： __declspec 。 GNU的__attribute__扩展也是如此。 [...]什么也不做，doxygen会感到困惑，并将__declspec视为某种功能。 [...]

因此，关于我上面的示例，在Doxygen配置文件中需要配置的设置如下：

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
PREDEFINED             = _Success_(x)= \
                         _In_=

基本上，这组配置意味着PREDEFINED部分中定义的宏将“ 在启动预处理器之前 ”进行完全扩展和评估。 但是，这些宏将扩展为空，因为我们为等式的定义端（即格式： name=definition ）提供“无”。 因此，在Doxygen生成文档文档时，它们实际上将被忽略/删除。

不幸的是 ，这确实意味着人们将需要继续扩展这个PREDEFINED列表，以至少封装源代码中使用的所有SAL宏。 一种更好的解决方案是将所有SAL宏封装在此列表中，但是将来的证明是不可能的，因为在以后添加任何新的宏时总是会很晚。 但是，至少有解决方案！