[boost] Re: Reference documentation: one approach

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

AlisdairM