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

From: Jonathan Brandmeyer (jbrandmeyer_at_[hidden])
Date: 2004-09-12 21:50:00

On Sun, 2004-09-12 at 21:45, David Abrahams wrote:
> 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.

Well, you can reverse the process to have Doxygen see the declarations
of functions that are implemented in the parent:

#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace detail {
class base
{
 public:
    void some_func();
};
}
#endif

#ifndef DOXYGEN_SHOULD_SKIP_THIS
class public : public base
# else
class public
#endif
{
// ...
#ifdef ONLY_DOXYGEN_SHOULD_SEE_THIS
    /** This function does stuff */
    void some_func();
#endif
};

However, the result is somewhat unclean, and since the docs are no
longer at the site of the code they are actually documenting, you've
lost the principle benefit of using Doxygen in the first place.  That
said, I think it would be very difficult to implement an in-code
documentation system that handled this case cleanly.

-Jonathan