"Reece Dunn" <msclrhd@hotmail.com> writes:
David Abrahams wrote:
"Reece Dunn" <msclrhd@hotmail.com> 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