Boost logo

Boost :

From: Alisdair Meredith (alisdair.meredith_at_[hidden])
Date: 2002-10-30 14:21:05

As someone who will be using this documentation rather than generating
it I'm not sure how relevent my comments might be, but it's never
stopped me before <g>

Jeff Garland wrote:

> I believe that the doxygen commenting format will handle almost all of Doug's list and those that it doesn't can be added. So,
> for example we a fully annotated function would look something like:
> //! This is the brief comment for a function
> /*! This is the long comment for the function.
> ...
> ... still the long comment....
> @param foo Description of the foo parameter
> @param bar Description of the bar parameter
> @return Description of the return value
> @pre Precondition 1
> @pre Precondition 2
> @post Postcondition 1
> @throws Exception commentary
> -- you get the idea
> */
> int f(int foo, double bar);

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. With doxygen I have no choice but to wade
through moderately detailed documentation at all times.

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?]


Boost list run by bdawes at, gregod at, cpdaniel at, john at