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

[Andreas Färber]

Am 15.12.2011 11:29, schrieb 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).

Hm, the navigation is what I dislike about the doxygen-generated example:

http://wiki.qemu.org/docs-internal/
http://qemu.weilnetz.de/doxygen/

doxygen looks to be oriented more towards C++, with a "Class Hierarchy"
that's completely flat.

Is either of the two able to understand qdev or QOM inheritance?

Andreas

-- 
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer; HRB 16746 AG Nürnberg