Peter Moulder wrote:
/* 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.
One general problem is that comments are very often not updated. Also... the farther the comments are from the actual code in question (the .h in this case) the less the likelyhood of keeping the comments in sync.
In general, things like "See end of" just don't help that much. If it's not 'right there' and trivial to keep up, docs and comments get out of date.