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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk