配置 Doxygen 以忽略源代码注释语言 (SAL)答案

【问题标题】：Configure Doxygen to ignore the Source-Code Annotation Language (SAL)配置 Doxygen 以忽略源代码注释语言 (SAL)
【发布时间】：2018-08-08 08:08:14
【问题描述】：

我有一些使用 Doxygen 记录的类。此外，它们还使用 Microsoft 的源代码注释语言 (SAL) 进行注释，以支持静态代码分析。

//! The majestic class.
class Foo {
    //! \brief do something
    //! \param [out] pResult The result value is stored here.
    //! \returns The return value Succcess indicates success.
    _Success_(return == Success)
    virtual Result_t DoSomething(_Out_ uint32_t *pResult) = 0;
};

在这种情况下，Doxygen 会报告一个警告：

在 Foo::_Success_(return==Success)=0 的参数列表中找不到命令 @param 的参数 'pResult'

所以，Doxygen 被注释语句 _Success_() 弄糊涂了。如何隐藏返回值注释 _Success_(return == Success) 去氧没有给源文件添加混乱？这可以完成工作，但看起来太冗长了：

//! The majestic class.
class Foo {
    //! \brief do something
    //! \param [out] pResult The result value is stored here.
    //! \returns The return value Succcess indicates success.
    //! \cond INTERNAL
    _Success_(return == Success)
    //! \endcond
    virtual Result_t DoSomething(_Out_ uint32_t *pResult) = 0;
};

这可以通过配置 Doxygen 并保持源代码不变来实现吗？

【问题讨论】：

标签： c++ doxygen sal

【解决方案1】：

在Preprocessing一章的doxygen手册中有一段：

需要预处理器帮助的典型示例是在处理来自 Microsoft 的语言扩展时：__declspec。 GNU 的__attribute__ 扩展也是如此。这是一个例子功能。

在您的情况下，以下可能会起作用：

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

【讨论】：