Boost logo

Boost :

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, gregod at, cpdaniel at, john at