example of killer doxygen formatting

[Richard Andrews]

>> Do we want to use the Qt style or the JavaDoc style?
>
> Personally, I'd rather use triple-slashes (ie, one-line javadoc style)

Personally I like the JavaDoc comments better.

Beyond personal choice, which version is more widely accepted? Doxygen is
killer, but it won't necessarily always be the best system and we should
consider that people may want to use other doc generators.


Another related question: do we use \ or @ for structured tags, and do we
use the structured tags at all?

Eg.

/** @brief This is a groovy function.
 *
 * @param p1 This is the grooviest parameter.
 */

or

/** \brief This is a groovy function.
 *
 * \param p1 This is the grooviest parameter.
 */

You can certainly do a lot for the formatting of the doc by making use of
@param, @return, @pre, @post, @sa etc. as well as just adding descriptions.