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

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

Jonathan Brandmeyer <jbrandmeyer_at_[hidden]> writes:

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

Of course I disagree ;-)

You just need a collapse-to-derived directive with which you can
annotate a class.  I wonder how Synopsis is doing these days...

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