-----Original Message----- From: Jon A. Cruz [mailto:jon@...18...] Sent: donderdag 16 oktober 2008 18:41 To: Engelen, J.B.C. (Johan) Cc: tweenk.pl@...400...; inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] documentation effort
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.
Personally, I don't care too much about compile time; but many people do, judging from past emails on the list after just a couple commits that changed e.g. verbs.h. If we start working on documentation, we can expect many small commits (e.g. just a typo fix).
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.
This does not mean their documentation isn't changed frequently.
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.
I myself find browsing through a header file with documentation very annoying. I like to look at a header file and see all methods etc at a glance. With lengthy documentation in it, it can be much harder for example to see whether a particular method is private or public. Without documentation you can quickly find which methods exist, check the exact spelling of some function or the exact order of parameters. Otoh, it is cumbersome to add documentation about a member variable in the cpp file. I guess it depends on why one looks in a header file; I almost exclusively look there to see which functions there are and what the spelling was or the param order. So, maybe a good compromise would be to add documentation about methods in the cpp file, and documentation about members in the header file. Documentation about methods can be lengthy and can contain many details, documentation about members is usually much smaller; so the header file won't be so bloated.
I guess for libraries, the documentation almost has to be put in header files, as the user only has those available (and the cpp files compiled to binaries). Something that's important to think about for lib2geom.
In any case, I started the documentation thread because of 2geom. I don't think there will be a big documentation effort on Inkscape. (Hope I didn't put anybody off with this comment, of course all documentation is very much appreciated!)
Cheers, Johan