header file documentation style

[Benoit Grégoire]

> * 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. Therefore in this case the @brief explanation only
> makes it more difficult to browse through the list of all available
> functions (because of the extra line breaks) -- and makes it harder to see
> all functions that belong together. There might be a few functions where
> the @brief comment helps a lot in clarifying, where the name itself would
> not be enough -- those would be fine, of course.

Agreed, with better (and longer) categories, it takes too much space.  But 
brief must be mandatory for files, 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.

> * I'd propose to use the automated grouping of doxygen (/**@{*/ ...
> /**@}*/) rather conservatively. Those groups help a great deal in
> organizing functions that belong together i.e. work on the same types
> and/or do the same things. I think of it in terms of a C++ class definition
> -- in such a definition, I can see *all* functions (C++: methods) that work
> on this type (C++: class). Since originally doxygen would only give me the
> list of 100 defined functions in one particular header file, we can use
> these groups to break down the 100 functions into reasonable-sized groups
> of stuff that belongs together. By this I mean: a) for a given type we
> should try to have as little different groups as possible, and b) to
> achieve this, a group should only be created if it contains at least 5...10
> functions in it. Ex: There are ~80 functions related to the type Split in
> Transaction.h. Since no developer can see 80 functions at the same time to
> pick the function he needs, we need to group these into logical groups. In
> this case, I came up with six different logical groups, each containing
> 10-20 different functions. I think it would be no good if there were much
> more groups than this, since then the developer will not be able to see all
> the groups at the same time. blablablable... gee  it's really getting late
> here. Hope you can follow so far.

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.  

 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.  My solution was 
modules.  Seems to work pretty well so far.  
-- 
Benoit Grégoire
http://step.polymtl.ca/~bock/