On Oct 16, 2008, at 2:48 AM, J.B.C.Engelen@...1578... wrote:
-----Original Message----- From: Krzysztof Kosiński [mailto:tweenk.pl@...400...] Sent: donderdag 16 oktober 2008 3:06 To: inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] documentation effort
There is one more to think about - where do we put the documentation? Do we put it in the header files like every library I have seen to date, or in the .cpp files where the functions are defined?
Preferrably in the cpp files, since this reduces recompilation times by a lot.
I disagree.
The .h files are supposed to be the public interface for a class or code. Also once an API is created, it should change very rarely, as opposed to the implementation which is in .cpp files and is expected to change often. And given that documentation doesn't change nearly as much as implementation, one shouldn't see frequent compiles triggered by doc changes. For files that might be included by many others (and thus be prone to triggering long recompilations) the fact that they are included by many other files would indicate they are core classes that many other things depend on and thus should see their API change even less frequently that others.
It also helps developers in day-to-day use. One only has to open a .h file to see the complete documentation for a class, with all methods documented one after another. If the documentation is placed in the .cpp file one would have to look in one file to see what a method is, then open a second much larger file and search throughout to finally find the implementation with the docs attached.
(A minor follow up to reduce compile times is to reduce the number of .h files being included and to avoid having .h files include other .h files)