From: David Abrahams (dave_at_[hidden])
Date: 2004-09-12 20:44:08
"Reece Dunn" <msclrhd_at_[hidden]> writes:
> David Abrahams wrote:
>>"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.
> I suppose it depends what you are doing. If you are just
> inputting/outputting an object, then you don't need to be concerned
> with how things like boost::io::pairfmt() are implemented. However,
> you will need to know the object that pairfmt() returns if you want to
> save that type for use later
Clearly the result type of pairfmt is not an implementation detail.
This doesn't have to do with "what you're doing," it's something that
-- except in very unusual situations where there's a good reason to
leave it unspecified -- one would clearly put in the reference
documentation that describes the library's interface. This is what I
mean when I say that reference docs can't be written as an
-- Dave Abrahams Boost Consulting http://www.boost-consulting.com
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk