header file documentation style

[Christian Stimming]

-----BEGIN PGP SIGNED MESSAGE-----

On Sonntag, 8. Dezember 2002 08:52, Benoit Grégoire wrote:
> > * I'd propose to not use the @brief comments in the regular case. In
> > functions like xaccTransSetDescription, it is already pretty clear what
> > this does from the name. 
>
> Agreed, with better (and longer) categories, it takes too much space.  

Yes, that's what I meant.

> But brief must be mandatory for files, 

Absolutely agreed, yes.

> so the brief description shows up in the
> file list.  Actually, coming up with good comands to place at the top of
> the files is what I spend most of my time on.  The system I came up with
> will allow us to document the internals (private headers and c files)
> without crowding the documentation unless requested specifically by the
> developper.

Really? That's cool. I would already be very satisfied if simply the 
(non-private) header files are documented. But if you found a way to do even 
more than that, then that's even better.

> > * I'd propose to use the automated grouping of doxygen (/**@{*/ ...
> > /**@}*/) rather conservatively. 
>
> Oh I follow you perfectly, and I agree we have to be conservative with
> categories, even if that means documenting more trivial functions.  We must
> also remember to make sure our category names start with the the name of
> the structure (Trans, Split) that they are related to, so when sorted
> alphabetically, they group related functions well.

Yes, agreed too.

>  I've been playing with EXTRACT_ALL, to see how we could navigate all this
> once more or less everything will be done.  Gnucash is huge.  

Indeed... 300k lines of code...

> My solution was modules.  Seems to work pretty well so far.

Cool. I'm looking forward how this turns out.

Christian
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iQCVAwUBPfNTmWXAi+BfhivFAQF1RQP7BjhduSVS3dw1ecpGJg0dUD3D9zw4jHmk
Lk/dBg/Uy+4bVJ8EGj8GG1uLREazO38DKrSA/i4XtSAI7ntF3ocb/g5u/+w1+VIc
VKqYtEmK45lhgHfNqNdHKj4jAnd7js+IlcmaWcyFhicprjEDZj9eQS2N0la7iLBG
snoEm64QsHs=
=F1B0
-----END PGP SIGNATURE-----