GnuCash developer documentation

[bock@step.polymtl.ca]

En réponse à Derek Atkins <warlord@MIT.EDU>:

> I agree.
> 
> I would MUCH rather see documentation in the header files than in the
> sources.  The sources should be _commented_ so you understand how a
> function works internally (i.e. what the implementation is), but the
> FUNCTIONAL INTERFACE is defined in the header file.  THAT is where the
> INTERFACE documentation should live.
> 
> When I want to khow about the interface for xaccTransGetSplits(), I
> want to be able to read Transaction.h -- I do NOT want to have to
> grovel through Transaction.c to figure out how the function works.

I do not.  Indeed logically the functional interface is defined in the header
file.  However, considering the header files are most commonly (correct me if I
am wrong) used to quickly look up/copy-paste a function prototype.  Also
considering that I think the #1 reason most developers do not systematically
document all their functions, is that the only way to make comments easy to read
and good looking is to build 80 columns boxes around them.  But that is just
painfull to do.  So I see the following practical problems with putting most doc
in the headers:

-Doxygen comments usually do not look very good (They can be made to look good,
but boxing them is even harder that usual, as the stars sometimes have meaning.)
   Most won't do it.  So to keep the headers easy to read directly (whis I agree
is sometimes very useful) I believe the amount of doxygen tags and verbosity
should be kept to a minimum in the headers.
-Some headers,  especially in the engine are already very large. 
(Transaction.h, Account.h, etc.)  They could easily triple in size if all the
functions were documented in the header, along with explicit parameter
documentation.  A 20+ page header is just not funny.  If we move the current
comments in the source and just put a /brief in it's place, the curent headers
would shrink in size, making them (IMHO) more usefull for looking up functions.
-It's true that when function prototypes change,  the developpers will probably
update the docs in either .c or .h.  That's the easy part.  But what if the
developper doesn't change the prototype.  For example, what if NULL is now an
acceptable value for a parameter, or what if while fishing for a bug the
developper just noticed that the function takes ownership of a pointer and that
wasn't documented?  I think he is far more likely to remember (or take the time)
to document it in the source than if he has to open the header, find the
function, and update the doc there.
-I think you just underestimate the value of the whole system ;)  Looking up a
function or a file is trivial when you have the html doc open.  Unlike you old
timers, I (and I am sure just about everybody younger than me) don't have emacs
keybinding hard-wired into my brain :)  I for one only use header files as full
documentation if there is nothing better available (sadly that is usually the
case).  I may be projecting my personal tastes a little, but I don't think
switching to a web browser and looking up a function is more work than opening a
file in emacs and switching tab.  Actually, I just realised that most people are
now are just about born with a web browser,  (My god, it's been 8 years since I
started working in computers, where did time go?)
-All docuemntion in the header (/bried and full description) leaves NO docs in
the source.  Having to look somewhere else to know what a function does (ok that
may be pushing it a little) or paremeter description isn't all that convinient
while hacking on somebody elses code.

But at least, as far as the output go, it just doesn't matter where the doc is
actually written.  So I'd gladly accept a little lack of uniformity in exchange
for full documentation.  Perhaps we should leave this for each developper to
decide, according with his own work habits?