GnuCash developer documentation

[Christian Stimming]

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

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
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iQCVAwUBPeVRBmXAi+BfhivFAQGmogP/XYM4NxfUrC87ImJ2hXUU/9dTBzAujCkn
OzzZJTPv+eMB/vy1VQkw2CO02LYXvZ/hL48EuP6NKxxbdVp1YFv/5WmnrIrMSeGX
15Xo5UUi5FO7umANypbb+lwH3GXY/bloNwzj8adpLeAfyHWmeULg8gsgPA56+Wt6
6qR2DDV05Fg=
=aITk
-----END PGP SIGNATURE-----