3

我正在尝试使用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: 警告：在Success (return)的参数列表中找不到命令 @param 的参数 'i'

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

4

1 回答 1

4

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

问题的答案引用了 Doxygen 手册部分，标题为：Preprocessing。

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

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

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

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

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

于 2019-07-19T22:17:40.403 回答