I've recently been playing with using doxygen for inkscape's sources. For the most part the changes are uncontraversial. In this and a future post are the couple things that I thought people may want to comment on.

Moving documentation from a .h file to a .cpp file --------------------------------------------------

While updating the documentation for a member of SPCurve, I used some text that I thought might need changing [indeed it already has changed]. Sometimes people are hesitant to change documentation in a .h file, as doing so can cause lots of ~needless recompilation.

As mental once mentioned, doxygen allows putting doc comments in .cpp files instead of .h files. The best example of this is documenting a non-inline function: the doc comment can precede the definition in the .cpp file instead of its declaration in the .h file. Doing so has the additional benefit that the comment is more likely to be kept up to date for changes to the definition.

A more questionable possibility is to store documentation for a struct/class in a .cpp file instead of the .h file where the type is defined. I've experimentally done this for SPCurve: the .h file now has a single comment

/* See end of curve.cpp for doxygen documentation. */

One reason that it's questionable to move the documentation away from the definition of the type is that doing so requires extra doxygen directives to say what the the comments pertain to. (See end of curve.cpp in CVS.)

Will moving the documentation away from the definition result in people not updating the documentation for changes to the definition? The `See end of curve.cpp' comment should mitigate this problem. Also keep in mind the already-mentioned reduced disincentive to edit comments in .cpp files compared to .h files, which tends to increase accuracy of comments kept in .cpp files compared to .h files.

Regarding convenience of reading the documentation: I'd guess that at some point doxygen will be the preferred way of accessing doc comments (e.g. using doxygen under emacsen; not sure about vim, but possibly one can use vim's existing tags support). When using doxygen to access documentation, it shouldn't matter whether we use the .h or .cpp file.

Whereas if not using doxygen, then there's an advantage to storing in the .h file: e.g. people can use a standard tag search to get to the type's definition. Consequently one might recommend "keep the doc comment with the type definition for now, and we may move to .cpp files later. Or decide based on how widely-#included the .h file is and how often the documentation is likely to change."

In any case, no doubt people's responses in this thread will influence people's case-by-case decisions as to where to put the documentation.

pjrm.