配置Doxygen以忽略源代码注释语言(SAL) [英] Configure Doxygen to ignore the Source-Code Annotation Language (SAL)

问题描述

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

I have some classes that are documented with Doxygen. Additionally, they are annotated with Microsoft's Source-Code Annotation Language (SAL) to support static code analysis.

//! 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报告警告:

In this case, Doxygen reports a warning:

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

argument 'pResult' of command @param is not found in the argument list of Foo::_Success_(return==Success)=0

因此，Doxygen被注释语句_Success_()弄糊涂了. 如何隐藏返回值注释 _Success_(return == Success) 去氧 不会在源文件中添加混乱?这样就可以了，但是看起来太冗长了:

So, Doxygen is confused by the annotation statement _Success_(). How can I hide the return value annotation _Success_(return == Success) to Doxygen without adding clutter to the source file? This does the job, but looks too verbose:

//! 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并保持源代码不变来实现吗?

Can this be implemented by configuring Doxygen and leaving the source code untouched?

推荐答案

在doxygen手册的Preprocessing章中，有一个部分:

In the doxygen manual in the chapter Preprocessing there is a part:

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

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. Here is an example function.

在您的情况下，以下方法可能会起作用:

In your case the following would probably work:

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

这篇关于配置Doxygen以忽略源代码注释语言(SAL)的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！