我正在尝试使用 Doxygen记录一些使用 Microsoft Source-Code Annotation Language (SAL) 的 C++ 代码.但是,Doxygen 不解析某些注释宏,例如 _Success_
,正确。对于示例函数注释,_Success_
,Doxygen 错误地将此宏解释为函数头/原型(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_()
解释为函数头/原型(prototype),从而创建完全错误的文档。以下是 HTML Doxygen 输出显示为有 和没有函数注释:
通过函数注解,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和 Doxygen只是不兼容?
最佳答案
啊哈! 经过进一步研究,我发现了一个 question在 Stack Overflow 上提出了同样的问题,只是没有正确标记并且没有明确说明他/她正在使用“Microsoft 的 SAL”。这就是为什么我花了一段时间才找到它。 (我已经更新了相应的问题以纠正这些错误。)
question's answer引用标题为:预处理的 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
部分中定义的宏将“在预处理器 [has] 启动之前”完全扩展和评估。但是,这些宏将展开为空,因为我们为等式的定义端提供“空”(即格式:name=definition
)。因此,当 Doxygen 构建文档时,它们基本上被忽略/删除。
不幸的是,这确实意味着需要继续扩展此PREDEFINED
列表以至少封装源代码中使用的所有SAL 宏。更好的解决方案是将所有 SAL 宏封装在此列表中,但 future 的验证是不可能的,因为在附加任何以后添加的新宏时总是会迟到。 但是,至少,有一个解决方案!
关于c++ - 将 Microsoft 的源代码注释语言 (SAL) 与 Doxygen 一起使用?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/57118340/