使用微软的源代码注释语言(SAL)与SAL？

Question

我试图使用含氧来记录一些使用微软源代码注释语言(SAL)的C++代码。但是，does不能正确解析某些注释宏，比如_Success_。在示例函数注释中，_Success_、macro将这个宏错误地解释为函数头/原型。

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

/**
 *    @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;
}

有了上面的例子，wrong将把_Success_()解释为函数头/原型，从而创建绝对错误的文档。下面是HTMLD氧气输出显示为的和没有的函数注释：

​

​

使用函数注释，also还说，我已经记录了一个参数变量i，它不是参数列表的一部分：

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

是否缺少主DO2配置文件中的配置设置？

或者是 销售 和 含氧 就是不兼容的？

Answer 1

啊哈！，经过进一步的研究，我在堆栈溢出上发现了一个问题，它提出了同样的问题，只是它没有正确标记，也没有明确地说s/他在使用“微软的SAL”。所以我花了一段时间才找到它。(我已更新了相应的问题，以纠正这些错误。)

问题的答案引用了The手册中题为:预处理的部分。

在处理来自Microsoft：__declspec的语言扩展时，需要来自预处理程序的帮助的一个典型例子是。GNU的__attribute__扩展也是如此。..。当什么都不做时，doxygen会感到困惑，并将__declspec视为某种函数。..。

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

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

基本上，这组配置意味着“在预处理器启动之前”，PREDEFINED部分中定义的宏将被完全展开和评估。但是，当我们为方程的定义端(即格式：name=definition)提供" nothing“时，这些宏将扩展到零。因此，在are构建文档文档时，它们基本上被忽略/删除。

Unfortunately，--这确实意味着需要继续扩展这个PREDEFINED列表，以封装源代码中使用的所有SAL宏。一个更好的解决方案是封装这个列表中的所有SAL宏，但是将来的校对是不可能的，因为在后面添加任何新的宏时总是会迟到。但是，至少有一个解决办法！