J.B.C.Engelen wrote:
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.
Actually, I think putting docs in headers would force people to make decent docs the first time they write them, because each change will trigger a rebuild of a large part of Inkscape. Right now they usually make skimpy documentation with the intent to expand it later, but in the end it never happens. It will also encourage people to document more at once - if they know a documentation change will trigger a rebuild, they will be more inclined to ensure it's worthwhile.
Another consideration is that for virtual base classes like XML::Node you have to put docs in the headers anyway, or in a completely separate file, but that defeats the purpose of Doxygen.
J.B.C.Engelen wrote:
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.
The solution is to look at the generated docs instead. Additionally Doxygen can generate an annotated source so you can read the header without all the doxycomment clutter if you wish. I find that using Firefox to page through Doxygen docs created with EXTRACT_ALL and cross-references along with a regular text editor can be a fairly decent substitute for an IDE. But that may be just me :).
Regards, Krzysztof Kosiński