RE: [boost] Reference documentation: one approach

From: David Bergman (davidb_at_[hidden])
Date: 2002-11-04 12:58:15

Gerhard,

I think the way to go is to have both the hand-written and automated
parts "linked" together, with possibilties to refer to the automated
classes/method/templates.

A very concrete problem I had with Doxygen (see your fifth '*') was
"free items", i.e., "\item" without an environment.

/David

-----Original Message-----
From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]] On Behalf Of Gerhard Wesp
Sent: Monday, November 04, 2002 5:23 AM
To: Boost mailing list
Subject: Re: [boost] Reference documentation: one approach

> I've never encountered this problem. Could you send me some code that 
> you think doxygen can't handle or point me to what type of construct 
> you've seen this with?

We're using doxygen on a commercial project.  I too have encountered
massive problems.  In particular, the issues are:

* It sometimes segfaults.
* Sometimes, errors or warnings are reported without file/line number
  information (<unknown>:-1: Warning: ...).
* There are problems with namespace lookup (many unjustified 
  ``no matching class member'' warnings.
* LaTeX seems to have problems compiling the generated source.
  (``string pool overflow'')
  Note that this can be fixed by ``enlarging'' LaTeX.
* Even if the LaTeX code compiles, there are still multiply defined
  labels.
* Sometimes, the generated LaTeX *does not* compile (with rather
  inexplicable errors).

The problems were with version 1.2.17.

Personally, I prefer hand-written documentation in favour of
automatically generated docs.  You get much cleaner and better
structured documents with basically the same, if not less, effort.

-Gerhard
-- 
| voice: [phone]  ***  web: http://www.cosy.sbg.ac.at/~gwesp
|
| Passts auf, seid's vuasichdig, und lossds eich nix gfoin!
|  -- Dr. Kurt Ostbahn
_______________________________________________
Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost