Doxygen comments in code

[Phil Edwards <pedwards at disaster dot jaj dot com>]

On Wed, Apr 25, 2001 at 01:33:21PM +0200, Gabriel Dos Reis wrote:
> Benjamin Kosnik <bkoz@redhat.com> writes:
> 
> | Personally, I'd rather use triple-slashes (ie, one-line javadoc style)
> 
> Likewise.

Well, that's quorum.  JavaDoc-style (/**, ///) it is!

I'd like to start playing with adding special comment blocks, because
if we're going to have something that's even moderately useful for 3.0,
we've a lot of typing to do.  :-)

To that end, I'm soliciting opinions on what we should document for each
public class, variable, and function.  Just an overview?  Each parameter?
Something in between those two?  Keep in mind that we can release an
encyclopedia if we want for 3.1.  Also keep in mind that the more we want
documented, the more help I'll need (my wrists get sore enough from typing
already :-).

Initially I'd like to drop placeholder text in everywhere we plan on
documenting for 3.0; that way people can easily see whether a particular
thing has been documented yet or not.  Contributors then don't have to
ask where/what/whether a thing should be documented.

Friends, coders, countrymen, lend me your thoughts...


Phil

-- 
pedwards at disaster dot jaj dot com  |  pme at sources dot redhat dot com
devphil at several other less interesting addresses in various dot domains
The gods do not protect fools.  Fools are protected by more capable fools.