将 Microsoft 的源代码注释语言 (SAL) 与 Doxygen 一起使用?
Using Microsoft's Source-Code Annotation Language (SAL) with Doxygen?
我正在尝试正确使用 Doxygen to document some C++ code that uses Microsoft's Source-Code Annotation Language (SAL). However, Doxygen does not parse certain annotation macros, like _Success_
。在示例 函数注释 、_Success_
的情况下,Doxygen 将此宏错误解释为函数 header/prototype.
以包含函数注释标记的以下示例为例:
/**
* @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_()
解释为函数 header/prototype,从而创建完全错误的文档。下面是 HTML Doxygen 输出看起来像 with 和 without function annotation:
通过 函数注解 ,Doxygen 还说我记录了一个不属于参数列表的参数变量 i
:
C:/.../Source.cpp:9: warning: argument 'i' of command @param is not found in the argument list of Success(return)
我是否缺少主要 Doxygen configuration file 中的配置设置?
或者 是 SAL and Doxygen 只是不兼容?
啊哈! 经过进一步研究,我在 Stack Overflow 上发现了一个 question 问了同样的问题,只是它没有正确标记并且没有明确地说 s/he 正在使用 "Microsoft's SAL." 这就是为什么我花了一段时间才找到它。 (我已经更新了相应的问题以纠正这些错误。)
question's answer 引用了标题为:Preprocessing.
的 Doxygen 手册部分
A typically example where some help from the preprocessor is needed is when dealing with the language extension from Microsoft: __declspec
. The same goes for GNU's __attribute__
extension. [...] When nothing is done, doxygen will be confused and see __declspec
as some sort of function. [...]
因此,对于我上面的示例,需要在Doxygen configuration file中配置的设置如下:
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = _Success_(x)= \
_In_=
基本上,这组配置意味着 PREDEFINED
部分中定义的宏将在“预处理器 [已] 启动 之前”完全扩展和求值。但是,当我们为等式的定义端提供 "nothing" 时,这些宏将展开为空(即格式:name=definition
)。因此,它们本质上是 ignored/removed 而 Doxygen 构建文档文档。
不幸的是,这确实意味着需要继续扩展此 PREDEFINED
列表以至少封装源代码中使用的所有 SAL 宏.更好的解决方案是将所有 SAL 宏封装在此列表中,但未来的验证是不可能的,因为在追加任何稍后添加的 new 宏时总是会迟到。 但是,至少,有一个解决办法!
我正在尝试正确使用 Doxygen to document some C++ code that uses Microsoft's Source-Code Annotation Language (SAL). However, Doxygen does not parse certain annotation macros, like _Success_
。在示例 函数注释 、_Success_
的情况下,Doxygen 将此宏错误解释为函数 header/prototype.
以包含函数注释标记的以下示例为例:
/**
* @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_()
解释为函数 header/prototype,从而创建完全错误的文档。下面是 HTML Doxygen 输出看起来像 with 和 without function annotation:
通过 函数注解 ,Doxygen 还说我记录了一个不属于参数列表的参数变量 i
:
C:/.../Source.cpp:9: warning: argument 'i' of command @param is not found in the argument list of Success(return)
我是否缺少主要 Doxygen configuration file 中的配置设置?
或者 是 SAL and Doxygen 只是不兼容?
啊哈! 经过进一步研究,我在 Stack Overflow 上发现了一个 question 问了同样的问题,只是它没有正确标记并且没有明确地说 s/he 正在使用 "Microsoft's SAL." 这就是为什么我花了一段时间才找到它。 (我已经更新了相应的问题以纠正这些错误。)
question's answer 引用了标题为:Preprocessing.
的 Doxygen 手册部分A typically example where some help from the preprocessor is needed is when dealing with the language extension from Microsoft:
__declspec
. The same goes for GNU's__attribute__
extension. [...] When nothing is done, doxygen will be confused and see__declspec
as some sort of function. [...]
因此,对于我上面的示例,需要在Doxygen configuration file中配置的设置如下:
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = _Success_(x)= \
_In_=
基本上,这组配置意味着 PREDEFINED
部分中定义的宏将在“预处理器 [已] 启动 之前”完全扩展和求值。但是,当我们为等式的定义端提供 "nothing" 时,这些宏将展开为空(即格式:name=definition
)。因此,它们本质上是 ignored/removed 而 Doxygen 构建文档文档。
不幸的是,这确实意味着需要继续扩展此 PREDEFINED
列表以至少封装源代码中使用的所有 SAL 宏.更好的解决方案是将所有 SAL 宏封装在此列表中,但未来的验证是不可能的,因为在追加任何稍后添加的 new 宏时总是会迟到。 但是,至少,有一个解决办法!