使用微软的源代码注释语言（SAL）和Doxygen？

Question

我正在尝试使用 Doxygen 来记录一些使用 Microsoft 的 源代码注释语言 (SAL) 的 C++ 代码。然而，Doxygen 无法正确解析某些注释宏，例如 _Success_。在示例的 函数注释 中，_Success_ 被误解为函数头/原型。

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

/**
 *    @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'在Success(返回)的参数列表中未找到

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

- Code Doggo

Answer 1

啊哈！经过进一步的研究，我在Stack Overflow上找到了一个问题，这个问题与我的问题相同，只是没有正确标记并且没有明确说明他们正在使用“Microsoft的SAL”。这就是为什么我花了一段时间才找到它。(我已经更新了对应的问题以更正这些错误。)

这个问题的答案引用了Doxygen手册中的一节： 预处理。

通常需要使用预处理器帮助的例子是处理来自Microsoft的语言扩展：__declspec。GNU的__attribute__扩展也是如此。[...] 如果什么都不做，doxygen将会感到困惑，并将__declspec视为某种函数。[...]

因此，针对我上面的示例，在Doxygen配置文件中需要配置以下设置：

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

基本上，这组配置意味着在预处理器开始之前将完全展开和评估PREDEFINED部分中定义的宏。但是，由于我们在等式的定义侧面提供“nothing”（格式： name=definition），因此这些宏会扩展为空，被忽略或移除，而Doxygen构建文档时则不会出现。

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

- Code Doggo