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

Question

我正在尝试使用Doxygen来记录一些使用Microsoft Source-Code Annotation Language (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 configuration file中缺少配置设置？
还是 SAL和Doxygen只是不兼容？

Answer 1

啊哈！经过进一步的研究，我在Stack Overflow上发现了一个question，它问了同样的问题，只是没有正确标记并没有明确说出他/她的意思。正在使用“ Microsoft的SAL”。这就是为什么我花了一段时间才找到它的原因。 （我已经更新了相应的问题来纠正这些错误步骤。）

question's answer参考了Doxygen手册的标题为 Preprocessing 的部分。

  

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

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

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

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

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