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

["Stephen M. Webb" <stephen at bregmasoft dot com>]

> From: Phil Edwards
> Some comments:
>
> 2)  Nearly all of the places where I've used /** comments instead
> of /// seem
> to require it.  For example, if the 4-line comment is changed to ///-style
> (which should be the same thing), doxygen doesn't see the documentation of
> namespace std.  This means that two whole categories of stuff
> just vanishes
> from the output (Namespace List (boring) and Namespace Members
> (important)).

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.

> 3)  Using special commands (they start with a @) seems to work better
> in the detailed mode (/** style) than in the brief mode (/// style).
> Possibly certain commands are not meant to be placed in brief blocks,
> I don't know.  Anyhow, where comments seemed to not be short, or had the
> potential to grow, or used @-commands, I went with the /** detailed mode.
> Yes, this would appear to suck in a C++ project, but there you have it.
> (I found that reading the source comments wasn't so bad after a while.)

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

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).

Just in case you needed the feedback.

_______
Stephen M. Webb