You are viewing a plain text version of this content. The canonical link for it is here.
Posted to proton@qpid.apache.org by Rafael Schloming <rh...@alum.mit.edu> on 2013/03/23 17:38:13 UTC

help with doxygen comment

My recent commit for PROTON-160 adds a doxygen comment that describes the
pattern matching syntax supported by the new pn_messenger_route API.
Because it is describing a pattern matching syntax, the character sequence
"/*" appears several times within the documentation. Initially this caused
gcc to barf with the warning that /* was appearing inside the comment
string. After googling a bit on the subject I couldn't find any practices
recommended by doxygen on this subject. In order to get my commit to work I
eventually added -Wno-comment to the flags in the cmake file.

Is there a better way to do this? Does doxygen support some kind of escape
sequences that would allow me to put some text that will render as /* in
the comment? Does anyone know if having /* in a comment is actually that
bad, i.e. will the -Wno-comment get us in trouble with other compilers?

Thanks,

--Rafael

Re: help with doxygen comment

Posted by Alan Conway <ac...@redhat.com>.
On 03/23/2013 12:38 PM, Rafael Schloming wrote:
> My recent commit for PROTON-160 adds a doxygen comment that describes the
> pattern matching syntax supported by the new pn_messenger_route API.
> Because it is describing a pattern matching syntax, the character sequence
> "/*" appears several times within the documentation. Initially this caused
> gcc to barf with the warning that /* was appearing inside the comment
> string. After googling a bit on the subject I couldn't find any practices
> recommended by doxygen on this subject. In order to get my commit to work I
> eventually added -Wno-comment to the flags in the cmake file.
>
> Is there a better way to do this? Does doxygen support some kind of escape
> sequences that would allow me to put some text that will render as /* in
> the comment? Does anyone know if having /* in a comment is actually that
> bad, i.e. will the -Wno-comment get us in trouble with other compilers?
>

Have you tried using /// comments? From doxgen doc:
----
A third alternative is to use a block of at least two C++ comment lines, where 
each line starts with an additional slash or an exclamation mark. Here are 
examples of the two cases:

///
/// ... text ...
///

or

//!
//!... text ...
//!

Note that a blank line ends a documentation block in this case.

----