Boost logo

Boost :

From: williamkempf_at_[hidden]
Date: 2001-03-12 10:02:19

--- In boost_at_y..., "Jeff Garland" <jeff_at_c...> wrote:
> > > I think that this is only the tip of the Iceberg. We really
need to
> > consider
> > > using something like Doxygen to generate XML models from the
actual code.
> > > Otherwise, you will be typing everything you want to document
twice, or
> > > extracting your header file from your XML (screaming heard in
> > background!).
> > > I use Doxygen for HTML output, but I believe there is an
experimental XML
> > output
> > > available.
> >
> > AFAIK there are still holes in Doxygen's parsing... and I assume
> > always will be ;-)
> This claim has been made on this list before and I consider it
bogus since I
> have been able to build documentation for STLport, Boost, and a
huge amount of
> other C++ code. There are holes in plenty of actual C++ compiler's
> too...that doesn't stop us from using them.

Bogus? I can name numerous parsing errors for Doxygen. The most
recent one discussed on the mailing list for Doxygen was the lack of
support for function-try-blocks (admittedly a rare thing in code
today). It also has problems with namespaces, often declaring the
namespace as a class and ignoring class names.

Don't get me wrong, I use Doxygen myself and think it's one of the
better comments-to-documentation tools available for C++. However,
to say that complaints about it's parsing ability are bogus is, well,
bogus. The good thing is that there's still active development on
Doxygen and parsing errors are addressed fairly quickly.

> > Maybe we should explore this instead:
> >
> >
> Looks like it has potential. Has anyone used it?

What I don't like about it is that it requires the use of GCC. What
we really need is a standalone utility that does this. Said utility
needs to be highly portable, much like GCC itself, but should not be
as complex or large as the full blown GCC compiler set.
> > Only this: unless someone is prepared to take this on and commit
to a
> > short-term date for delivery of a solution, we should really be
looking at
> > approaches which will not:
> > 1. Require a long learning curve
> > 2. Require much development to produce.
> > The rest may be of interest as theoretical ideas but if we need
solutions of
> > this sort (and I'm not sure we do, yet), we ought to keep the
> > issues in mind.
> Given these criteria we should stick with HTML....

Short term, definately. But, as pointed out, as the need grows for
the documentation to be formatted in different ways, such as printed
documentation, online docs, man pages, etc., we'll have to start
considering more powerful solutions. Though round-trip
engineering/documentation would be nice, I think we need to start
smaller with something as simple as DocBook. The other tools can be
added incrementally as solutions are found.

Bill Kempf

Boost list run by bdawes at, gregod at, cpdaniel at, john at