将 Microsoft 的源代码注释语言 (SAL) 与 Doxygen 一起使用？答案

【问题标题】：Using Microsoft's Source-Code Annotation Language (SAL) with Doxygen?将 Microsoft 的源代码注释语言 (SAL) 与 Doxygen 一起使用？
【发布时间】：2019-11-28 19:05:42
【问题描述】：

我正在尝试使用 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 输出的样子，with 和 without function annotation：

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

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

我是否缺少主 Doxygen configuration file 中的配置设置？
还是SAL 和 Doxygen 只是不兼容？

【问题讨论】：

标签： c++ windows winapi doxygen sal

【解决方案1】：

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

question's answer 引用了 Doxygen 手册部分，标题为：预处理。

处理 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 宏时总是会迟到。 但是，至少，有一个解决方案！

【讨论】：