GnuCash developer documentation

[Christian Stimming]

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

On Samstag, 23. November 2002 02:14, David Hampton wrote:
> On Fri, 2002-11-22 at 16:28, Matthew Vanecek wrote:
> > I whole-heartedly agree.  There are several great tools for creating API
> > references (e.g., javadoc, doxygen, etc).  
>
> Agreed.

Agreed too. If somebody asks, I'd vote for doxygen.

> > I really like Benoit's suggestion of moving documentation to
> > header/source comments, because it's much more likely to be kept
> > up-to-date there, than if it were a separately maintained entity.
>
> Source please, not header.  I know there are currently lots of comments
> in header files, but I prefer comments closer to the actual code and I
> think the are more likely to be updated there.  How much of your time do
> you spend editing .c files vs. .h files?

Header please, not source.

Seriously, if my parts of the code are using functions from somewhere else, 
then my code sees only the header files and so do I. The header file is the 
place where the declaration takes place, and ideally the comment in front of 
that declaration should give me absolutely enough knowledge to understand 
what that particular function is going to do. Contrary to that, a header file 
with undocumented declarations is pretty much useless for any human reader. 
Note that we have two different questions here: On the one hand, the comments 
should be in a place where the user/reader easily finds them. Which would be 
in the header. On the other hand, the comments should always be kept up to 
date by the developer. Which does happen or not happen pretty much regardless 
of whether the comments are placed in the header or the source -- developers 
can forget it in both places, or can remember that in both places. Therefore 
I would definitely vote for function documentation in the header.

Christian
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iQCVAwUBPd9sZGXAi+BfhivFAQE1jAP/Q4Sdy3rjscab/42COnGZnq6+VofiZEue
2gwHWIO4ZMA25oURwupF+Ec1Im/8FKoKDIKpiihnnf+J7Sst6lhuYT2KrJe8sUjV
AEJxOoHcxf0aNisAtAb1tP6DIrrOeHfzo4fvo1+SKiSgZ8r9hY1Nj5TJQCGfdqPV
nX35qOQs/1M=
=E+Bn
-----END PGP SIGNATURE-----