Re: revisiting gdoc

[Tom Tromey <tromey creche cygnus com>]

Dirk> A while ago I asked why we (ok, I'm not contributing any
Dirk> softwore to gnome right now) are not using doc++. Perhaps we can
Dirk> patch it to gdoc++ so that it supports DocBook. The answer was,
Dirk> that it is to complex. I'm not sure. I looked at it, and it
Dirk> seems very easy to me.

I think the difference is that the current system (in theory) parses
the actual C text.  That way your comments don't need to include type
and name info.

Your example:

Dirk> /** blah blah blah.
Dirk>     @param GtkWidget *target
Dirk>     @param int       gnomo_action
Dirk>     @return the number of gnomothings gnomoacted on. */

in the current system would look just like C code (because it is :-):

	/*
	 * blah blah blah
	 * Some stuff about the return value.
	 */
	int gnomo_do (GtkWidget *target,	/* The target.  */
		      int gnomo_action);        /* What action to take.  */


At least, that's the theory.  In practice, the gdoc stuff doesn't work
too well, and is C-only.


In the short term I'm afraid I'm just going to ignore documentation.
This is losing, I know, but I don't have the heart to struggle against
gdoc, and I want to work on things other than fixing it.

Tom