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

From: Jonathan Brandmeyer (jbrandmeyer_at_[hidden])
Date: 2004-09-12 14:08:37

On Sun, 2004-09-12 at 14:26, 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.

The Gtkmm project deals with this by adding the macro
DOXYGEN_SHOULD_SKIP_THIS to the PREDEFINED field in the Doxyfile.  Parts
of the code that should be not be in the user-level docs then get
bracketed with #if DOXYGEN_SHOULD_SKIP_THIS / #endif.  The GNU libstdc++
library uses a variation of this technique to generate separate
user-level and maintainer-level documentation.

HTH,
-Jonathan Brandmeyer