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. -derek Christian Stimming <[EMAIL PROTECTED]> writes: > Wow. This doxygen stuff is gonna be cool :-) Thanks a lot, Benoit. > > On Samstag, 23. November 2002 21:09, Benoit Gr�goire wrote: > > The header vs source debate is easily solved in doxygen. You put a /brief > > doxygen comment above the function declaration in the header, which is a > > single sentense describing the function. That sentense in unlikely to > > change very much over time. > > > > In the source, for the same function, you write the detailled description > > and usage, parameters and return value. This is what is likely to change > > over time. > > Err... I would definitely prefer to have the *full* function's documentation > *in the header*. What do developers want to know about functions? They want > one sentence saying what this thing is for. And they need to understand what > each function argument does. And they might need even more detailed > information about how this function is supposed to be called and used. > > I would especially consider the function argument explanation to be really > important, if the in-place comments should really help developers. I think > this is not an overly burden in the amount of file changes, since e.g. if the > arguments change the header file has to be changed anyway. > > > That way there is enough doc in the header to have a basic idea of what the > > function does, and if the developer wants more info, he can just fire up > > his web browser and look at the cross referenced doxygen doc. > > IMHO not really. A developer who is really down at coding will probably prefer > to have the documentation right in front of him, right in the header file of > the function he's looking at. The web browser doc OTOH is really great for > getting the greater picture, and to look up the really difficult things, and > during phases of more conceptual work. Blablabla. Whatever (getting late > here)... I'd vote for the complete function documentation right next to their > declarations, in the header file. > > Anyway, this docs are gonna be cool. Way to go, Benoit! > > Christian > > _______________________________________________ > gnucash-devel mailing list > [EMAIL PROTECTED] > http://www.gnucash.org/cgi-bin/mailman/listinfo/gnucash-devel -- Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory Member, MIT Student Information Processing Board (SIPB) URL: http://web.mit.edu/warlord/ PP-ASEL-IA N1NWH [EMAIL PROTECTED] PGP key available _______________________________________________ gnucash-devel mailing list [EMAIL PROTECTED] http://www.gnucash.org/cgi-bin/mailman/listinfo/gnucash-devel
