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

From: David Abrahams (dave_at_[hidden])
Date: 2004-09-12 20:45:38

Jonathan Brandmeyer <jbrandmeyer_at_[hidden]> writes:

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

I am talking about situations where the inherited members should
really be documented as members of the _derived_ class.  That was very
common for me in Boost.Python, and I don't think you can do anything
as trivial as marking regions to be skipped if you want to achieve it.

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