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

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

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