RFC on doxygen & man page style issue

[Phil Edwards <phil at jaj dot com>]

Imagine a situation like this:

    /**  special documentation */
    struct Base
    {
        /**  special documentation */
        public member #1 of the standard library;
    };

    /**  special documentation */
    struct Derived : public Base
    {
        /**  special documentation */
        public member #2 of the standard library;
    };

When the user pulls up the html documentation for Derived, or runs "man
std::Derived", he will always have the choice of clicking on parent Base
class and seeing the notes for member #1.  The question is whether member
#1 should additionally appear in the documentation for Derived.


Pros:
 - It's very handy for the user.
 - It's required for correctness with respect to numeric_limits, which is
    derived from a non-template base class.  Viewing the numeric_limits
    documentation only shows the member functions; we would have to add
    a note of "to see the static member data, view the docs for the
    implementation-specific __numeric_limits_base class," and that would
    be less than wonderful.

Cons:
 - Notes for the leaf classes in the I/O heirarchy become /gigantic/.
   (Trust me, I had this on for a while and got lost.)


I suppose we could conceivably run the doxygen routines twice, one with
each setting, and then copy various files from one tree into the other,
so that, e.g., numeric_limits is merged and I/O classes are not.  I don't
know whether I'm volunteering for automating that task, since there are
just over 1100 files generated at present, with oddly-generated names.


Phil

-- 
If ye love wealth greater than liberty, the tranquility of servitude greater
than the animating contest for freedom, go home and leave us in peace.  We seek
not your counsel, nor your arms.  Crouch down and lick the hand that feeds you;
and may posterity forget that ye were our countrymen.            - Samuel Adams