RE: [boost] Reference documentation: one approach

From: Petr Kocmid (pkocmid_at_[hidden])
Date: 2002-10-31 23:01:02

> David Abrahams wrote:
> "Ken Shaw" <ken_at_[hidden]> writes:
> > From: "David Abrahams" <dave_at_[hidden]>
> > > Doxygen has always failed miserably at understanding template code
> > > I've generated of any complexity.
> > 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?
> It's been quite a while, so, no I can't. I was running it on Boost
> sources, though.

I can name some bad issues I got with doxygen on templates year ago:

- nested namespaces (ugly doc structure)
- template member functions wrong
- partial specialisations wrong
- declarations and definitions of specialised member constants wrong
- compiler vendor extension type declarators misunderstood as functions

It was wery necessary to CHECK MANUALLY every piece of generated doc from my
templates.

I had to make many nasty macro workarounds to signatures to get the
documentation correct at least partially, obfuscating my preciouss code as
well as many hacks to my private branch of doxygen, just to keep doc for a
single project which needed to be well documented in both english and czech
languages.

The real problem is the template part of doxygen parser does not reflect the
language at all, it was added to originally non-template C++ version as a
hack.

Petr Kocmid