RE: [boost] Reference documentation: one approach

From: Noah Stein (Noah_at_[hidden])
Date: 2002-10-30 14:19:31

> Victor A. Wagner, Jr.:

> I've been using Doxygen for a couple (gee is it 3 already?) years
> and have
> found it easy to use for simple things, and possible to use for complex
> things.  I like especially that the "source" of the documentation
> is in the
> "source" of the program.

I've been using Doxygen for a few years, but it is currently lacking in a
few areas.  We had a discussion on the Spirit mail list a couple of months
ago about documentation solutions.  I proposed Doxygen at the time, but
after some testing I found that it both lacked the functionality (currently)
to process some of the most important aspects of Spirit while at the same
time requiring a layout that hid the structure of spirit.  Not that it can't
be extended, but Doxygen is not currently set up to handle a numbef of
meta-programming constructs, i.e.:

struct MetaPow {
    template
        < typename BaseType  ///< The class of the base being raised to a
power
        , typename PowType  ///< The class of the power to which the base is
raised
        >
    struct ReturnType {
        typedef BaseType type ///< The type of the power expression given
input types
    };

    template<typename BaseType, typename PowType>
    struct Apply {
        ReturnType<BaseType,PowType>::type operator()(BaseType base, PowType
pow);
    };
};

Okay, some of the comments are dumb, but it's quick and illustrates my point
:).  If I had fully documented the class above, I would run into a few
problems.  First, template parameters do not get documented.  In older
versions, the template parameter comments were ignored.  The last version I
used, circa 3 months ago, refuses to parse a class with inline template
parameter comments.  You'd get a page for MetaPow::ReturnType, but it would
have no information for any member, even though you'd fully documented the
class.  In this case, the information for MetaType::ReturnType::type would
not appear.

Eliminating the bug is probably pretty easy for Dmitri.  Adding support for
template parameter information is probably a bit more complicated.  But even
at that point, the documentation doesn't structure output to handle the
metafunction above.  ReturnType and Apply end up on their own pages.  IIRC,
there aren't even references to it on the MetaPow page, only in the various
indices and table of contents.  Since the two structures above really
represent a typedef and a member function, the output should be structured
to view them that way.

Because of these reasons, Spirit decided against using Doxygen.  I still use
Doxygen.  Most of my code, since its normal old-fashioned application code,
works well with it.  But boost code is highly templatized, so I doubt
Doxygen would be nearly as effective in dealing with it at present.

-- Noah