[boost] Re: Formal review of "Output Formatters" library beginstoday

From: David Abrahams (dave_at_[hidden])
Date: 2004-09-12 13:26:21

"Reece Dunn" <msclrhd_at_[hidden]> writes:

>>AFAICT the docs lack any sort of formalized reference guide, showing
>>interface summaries, what headers to include, requirements, etc.  IMO
>>it's unacceptable without that component.  Did I miss something?
>
> okay. IIUC, Doxygen will auto-generate these when provided
> javadoc-like comments.

You won't get Concept documentation from Doxygen unless you take care
to actually write it ;-), and regardless I don't think this can be
done as an afterthought.  I would be wary of taking this route unless
your implementation is very simple.  It's important to present a
coherent view of the *user interface* that doesn't expose
implementation details.  For example, sometimes public inheritance
from some helper class is neccessary as an implementation technique,
and you don't want to expose it, but you need to expose the public
members of that helper.  I don't think Doxygen can deal with that.

>>The lack of reference docs is a showstopper for me.
>
> okay. I'll look at getting doxygen up and running on my machine.

It'll be interesting to see how it works out.  Maybe I'm being overly
skeptical.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com