-----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----- _______________________________________________ gnucash-devel mailing list [EMAIL PROTECTED] http://www.gnucash.org/cgi-bin/mailman/listinfo/gnucash-devel
