Re: Boost Documentation [was Iterator Adaptors]

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 
the
> > 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 
there
> > 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 
parsers
> 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:
> > http://groups.yahoo.com/group/boost/message/8370
> >
> 
> 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 
practical
> > 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