From: Dominik Riebeling <dominik.riebeling_at_gmail.com>
Date: Sat, 11 Dec 2010 19:27:00 +0100

On Sat, Dec 11, 2010 at 1:26 PM, Marcin Bukat <marcin.bukat_at_gmail.com> wrote:
> 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

From my point of view inline documentation is the only sensible way.
If it's in the code itself it's much less likely to get overlooked on
changes. Also, if one is working in the code looking up the
documentation is pretty easy (especially if you're using tools like
ctags to directly jump to the function you want to look up). Therefore
the documentation should go in the source files and not the headers --
if the documentation is in header files it's more likely of not
getting updated (since working involves more changing the source than
the header file. Well, usually :)

The manual is a nice example why documentation that's maintained
separately pretty quickly gets out of sync (though I admit that for
the manual there are other reasons as well, but I believe the reason
that it's "out of view" for someone hacking the Rockbox code base is
not a minor one.)

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

Before we can start adding documentation we need to know which format to use :)

I'm in strong preference for Doxygen since it's IMO a quite natural
format that doesn't get in the way too much, especially if the Javadoc
Autobrief style is enabled. Also, since Doxygen is quite popular I
think it's a good choice. I'm willing to look into customizing the
Doxygen output if there is enough interest, I'll try to find some time
for that during the holidays.

From my point of view a Doxygen comment should look like the following:

/** Short summary, ending with a dot.
 *
 * Optional more detailed explanation. Can span multiple
 * lines.
 * _at_param parameter1 Description of parameter1 if necessary.
 * _at_return Description of return value (unless it's void).
 */
int function_name(int parameter1);

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

As said before I think those would be better placed in the source
files. Since all Doxygen comments start with a special marker people
who don't want to see those comments in the code should be able to
hide / fold them in their editor based on a regular expression.


 - Dominik
Received on 2010-12-11