RE: [boost] Re: Reference documentation: one approach

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.

Agreed.
 
> 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.

Jeff