Wdocumentation false positive warning for a \struct Doxygen with template

[andrei-sandor]

Here is a bug regarding a Doxygen annotation for a struct.

Given the file structDoxygenFinal.cxx:

/**
 * \struct BooleanDispatch
 * \brief A comment here
*/

template <bool>
struct BooleanDispatch
{};

int main ()
{
  return 0;
}

Run this command:

clang++ -Wdocumentation -std=c++14 -fsyntax-only structDoxygenFinal.cxx

The following warning will be generated

structDoxygenFinal.cxx:3:5: warning: '@struct' command should not be used in a comment attached to a non-struct declaration [-Wdocumentation]
 * \struct BooleanDispatch
   ~^~~~~~~~~~~~~~~~~~~~~~
1 warning generated.

To fix this warning, the comment could be placed between Template and struct BooleanDispatch in structDoxygenFinal.cxx

Is it fine, if in general, a Doxygen comment with \struct is placed between a template statement and a struct statement?

[Ecordonnier]

FYI doxygen doesn't require @struct when writing a comment above a struct. "@struct" can be omitted completely in this case. "@struct" is supposed to be used when documenting the struct in a documentation which is somewhere else (not above the struct).

[andrei-sandor]

Thank you for the response.