[cfe-dev] -WDocumentation warning on multiple defs in a single comment block

[Dmitri Gribenko]

On Thu, Jan 17, 2013 at 7:36 PM, Marshall Clow <mclow.lists at gmail.com> wrote:
> I have a chunk of code that looks like this:
>
>         /*!
>                 \struct hex_decode_error
>                 \brief  Base exception class for all hex decoding errors
>
>                 \struct non_hex_input
>                 \brief  Thrown when a non-hex value (0-9, A-F) encountered when decoding.
>                                         Contains the offending character
>
>                 \struct not_enough_input
>                 \brief  Thrown when the input sequence unexpectedly ends
>
>         */
>         struct hex_decode_error : virtual boost::exception, virtual std::exception {};
>         struct not_enough_input : virtual hex_decode_error {};
>         struct non_hex_input    : virtual hex_decode_error {};
>
>
> Doxygen processes it correctly.
> TOT clang (using -Wdocumentation) warns about duplicate \brief comments.
>
> Specifically, it says:
>         warning: duplicated command "\brief" [-Wdocumentation]
>
> Obviously, I can break this up into three comment blocks, but why should I have to?

Currently we don't process \struct and similar commands.  The reason
is that handling these commands is a much more complicated problem
than what we do now; I don't even think we can do it cheaply.  When we
process the comment, we need to first find the corresponding
declaration.  Currently we attach the comment to the next declaration
(basically).

To handle the situation you describe we would essentially need to
postpone parsing comments until the end of TU.  Maybe one day we will
do this (when we will parse declaration references in comments --
essentially the same problem), but we don't do it now.

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/