Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)

[Stefan Weil]

Am 15.12.2011 11:04, schrieb Daniel P. Berrange:
> On Thu, Dec 15, 2011 at 10:32:20AM +0100, Stefan Weil wrote:
> > Am 15.12.2011 06:22, schrieb Andreas Färber:
> > > Their website has the following:
> > >
> > > "GTK-Doc wasn't originally intended to be a general-purpose
> > > documentation tool, so it can be a bit awkward to setup and use. For a
> > > more polished general-purpose documentation tool you may want to look at
> > > Doxygen. However GTK-Doc has some special code to document the signals
> > > and properties of GTK+ widgets and GObject classes which other tools may
> > > not have."
> > > http://www.gtk.org/gtk-doc/
> > >
> > > Don't know if Doxygen has less restrictions though.
> > >
> > > Andreas
> >
> > With doxygen, the documentation looks like this:
> > http://qemu.weilnetz.de/doxygen/
>
> I don't know about others, but I find Doxygen output really unpleasant
> to read & navigate. I really despair whenever I find an API I need to
> learn that uses Doxygen. The output of GTK-DOC by comparison is so much
> more pleasant to consume.
>
> Regards,
> Daniel

I think that does not depend on the tools but on the people
who use them.

The output for the memory API is basically the same with
gtkdoc and doxygen:

http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html
http://qemu.weilnetz.de/doxygen/memory_8h.html#a13a3b6850223d2f5a691c618eee54610

(The doxygen output contains some additional information
because I selected to add graphs. Its information is partially
badly formatted or missing simply because the input file
was written for gtkdot and not for doxygen).

Good navigation needs special documentation input either
in the source code or in additional files and is possible with
doxygen as well (I use it since a couple of years).

Maybe those projects with good gtkdoc documentation
care more for their documentation (and spend more time)
than those projects which only have less good doxygen
documentation.

Cheers,
Stefan Weil