Search code examples
doxygenclang-static-analyzerclang-tidy

suppress clang-tidy -Wdocumentation "empty paragraph" errors

I can't seem to find where I might be able to suppress these specific errors or why they are even registering in the first place.

error: empty paragraph passed to '@param' command

Here is the documentation that I have that is generating this error:

//----------------------------------------------------------
///
/// @brief functionThatModifiesSomething
///
/// @param[in] param1
/// @param[in] param2
///
//-----------------------------------------------------------
void functionThatModifiesSomething(uint32_t param1, uint32_t param2);

I only noticed this because I am finally turning on some of these warnings and I'm cleaning up as I go.

After seeing the warning, I don't understand why it is registering an error when the @param is not an empty paragraph. Any thoughts? Can I suppress this flavor of documentation warning somehow?

Here is the full error:

./path/to/somefile.hpp:570:21: error: empty paragraph passed to '@param'     command [-Werror,-Wdocumentation]
/// @param param1
    ~~~~~~~~~~~~^

We are using Doxygen as our documentation format.

Solution

  • @param expects a description to follow the parameter name, which is missing in the above.
    So a possible fix may be:

    /// @param[in] param1 Description #1
/// @param[in] param2 Description #2

    See http://www.doxygen.nl/manual/commands.html#cmdparam for @param documentation.

    Clang's documentation warnings are enabled with -Wdocumentation, which is disabled by default. There's a whole bunch of documentation warning from different kinds, which are all enabled by -Wdocumentation, but unfortunately you can't opt out from individual warnings such as the "empty paragraph passed to @command" warning.