revisiting gdoc

[Tom Tromey <tromey creche cygnus com>]

I spent some time playing with gdoc tonight.  In particular, I started
writing some docs for `gnome-client.h'.

gdoc failed miserably.  It says "syntax error" while scanning the
header (for instance, it gives an error for my unistd.h, sigh), and
the final output is useless -- it says there are no descriptions in my
gnome-client.h.

It has some other problems as well.  I don't put my headers in
/usr/include or /usr/local/include, so I had to edit gdoc.pl to add a
-I option.  This is fixable, if we think it is worth the effort.

But is it?

My main concern is that the idea of scanning the comments to try to
reconstruct semantic information -- something you want to do so that
the generated DocBook is of high quality -- is fundamentally flawed.

I don't have a good example of this losing, though, since I can't even
get gdoc to reliably work.


gdoc is also C-only, which I don't like.


Is there some reason not to write comments in DocBook and extract them
verbatim?


Has anybody had better luck with it?

Tom