-----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----- _______________________________________________ gnucash-devel mailing list [EMAIL PROTECTED] http://www.gnucash.org/cgi-bin/mailman/listinfo/gnucash-devel
