En r�ponse � Derek Atkins <[EMAIL PROTECTED]>: > 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? _______________________________________________ gnucash-devel mailing list [EMAIL PROTECTED] http://www.gnucash.org/cgi-bin/mailman/listinfo/gnucash-devel
