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

[Kevin Wolf <kwolf@redhat.com>]

Am 15.12.2011 12:36, schrieb 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?

For C code, you can tell doxygen manually about inheritance by adding a
tag in the doxygen comments (iirc, it was something like "@extends
DeviceState").

Kevin