[patch] Doxygen markup for 18, 19, part of 20

Phil Edwards pedwards@disaster.jaj.com
Tue Jul 10 09:46:00 GMT 2001


On Mon, Jul 09, 2001 at 08:59:54PM -0400, Stephen M. Webb wrote:
> Multiline /// comments just don't seem to work.  They're intended for
> single line comments, and they seem to lose their association with
> the following code block if there is more than 1 line.

Unfortunately, they seem to work occasionally; see for example char_traits.
There's a 2 or 3 line /// comment, and it all shows up associated with the
code correctly.  It's a misleading misfeature which cost me some time.
Oh well.  I agree that multiline comments can't really be considered
"brief" anymore.  :-)


> The /** comments aren't C style, they're Java style.

Enh.  As far as the compiler is concerned, they're C.  *grin*  I prefer
to use "Java style" only when distinguishing from "Qt style", at least
when dealing with doxygen.


> I found in a project where I used doxygen that using /** comments for
> doxygen style comments consistently ended up a good thing, since I
> could tell at a glance what was official "documentation" (ie ended up
> on our intranet server) and what wasn't.
> 
> I also found that @param and @return commands were really useful, but the
> @brief command was useless (there is a switch in the config file that will
> autogenerate the equivalent, just like javadoc does).

I tried turning that on and stuff broke.  The other thing I don't like about
it is that the person writing the comments has to pay special attention
to the first sentence ("does this make sense on its own?") when writing
a large block.

@param and @return should go in (there's an example with make_pair now),
but that'll take more people.


> Just in case you needed the feedback.

Thanks!

Phil

-- 
Would I had phrases that are not known, utterances that are strange, in
new language that has not been used, free from repetition, not an utterance
which has grown stale, which men of old have spoken.
                                     - anonymous Egyptian scribe, c.1700 BC



More information about the Libstdc++ mailing list