header file documentation style

[Christian Stimming]

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

Benoit: the doxygen configuration works really nice. It finally looks as if we 
will arrive at a "real", exhaustive engine/gnucash API documentation. Very 
nice!

Just a few remarks about how IMHO doxygen's features can be used most 
efficiently. (I went through all this only recently -- HTML like  
http://openhbci.sourceforge.net/doc/api/classHBCI_1_1Bank.html is the 
outcome.) 

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

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

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

iQCVAwUBPfKsn2XAi+BfhivFAQF4CQQAs4hztUZicO+esnR9pnR8I/Q9hveZF2Yy
q52g4kE4a0iTHLipD8bDsdJIPthhQLsfjt2eRuLVbGRxdgD+yA8Z9S4SKia5Ff9a
lDQWt4xgWuQomY0I1Iafo3P+QgEtVAKD6cGdqEjGvPfnvb/0QmPrE7ieuGMRVaqs
0YNIVFtTpHE=
=qo+L
-----END PGP SIGNATURE-----