Opinions gathered here and on IRC boils down to the conclusion that
inline documentation is considered an option but there are concerns if
doxygen is the right tool to use. The first step to use concept of
inline documentation is to state the rule to add comments (in
particular format suitable for parsers) to the parts of code being
touched. This is independent from the tool used later to parse this.
Moreover comments are a good thing so we will only gain in stating
such rule even if we consider to not use doxygen-like tool at the end.
Looking at the doxygen documentation I think the most suitable format
for inline documentation is javadoc style:

/** Shor descritpion.
 *
 * Detailed description
 */

This looks quite natural and follows our rule to use C-style comments.

To conclude, I think stating the rule to put such comments in .h files
will be pure benefit.

Marcin Bukat (wodz)
Received on 2010-12-11