From: Jeff Garland (jeff_at_[hidden])
Date: 2002-10-30 14:44:39
> This illustrates my main issue with doxygen the time we flirted with
> it. It almost entirely obscures the source. Where before I could read
> a header file as simplified documentation, now I have a huge
> comment-to-source ratio making it very hard to pick out information
> quickly and easily. When I need this detailed view, I turn to the
> documentation (when available) but the majority of the time I prefer the
> 'cleaner' header file.
I agree totally. There are two solutions. For most projects I recommend
splitting the header declaration and the implementation. I always put
all the documentation in the implementation (.cpp) since that is where
the majority of changes are -- not to mention it is undesirable to
trigger of recompiles when modifying a header for documentation.
With this approach the header stays neat and compact. And BTW, it
is pretty rare to use all these options on a function since most
simple function don't require all this detail. But some of us have a
need to develop docs for the standard proposals...
> With doxygen I have no choice but to wade
> through moderately detailed documentation at all times.
You can use the generated documentation, fully hyperlinked docs with
all the comments stripped. I find this is much faster for traversing
large code bases then using an editor.
> Don't get me wrong, I LIKE documentation, but as a suplement to the
> source, not obscuring it.
> I would add that I worry how this will get on with the many boost
> libraries that are implemented in those same header files. [or is it
> common practice to doxygen source as well as headers?]
Yes, see above.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk