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;
};
In this case, Doxygen reports a warning:
argument 'pResult' of command @param is not found in the argument list of Foo::_Success_(return==Success)=0
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;
};
Can this be implemented by configuring Doxygen and leaving the source code untouched?
In the doxygen manual in the chapter Preprocessing
there is a part:
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)=