From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:50436) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rb9iq-0000Hq-0h for qemu-devel@nongnu.org; Thu, 15 Dec 2011 06:43:39 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Rb9ik-0005Ws-Bw for qemu-devel@nongnu.org; Thu, 15 Dec 2011 06:43:35 -0500 Received: from mx1.redhat.com ([209.132.183.28]:49840) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rb9ik-0005Wg-4T for qemu-devel@nongnu.org; Thu, 15 Dec 2011 06:43:30 -0500 Message-ID: <4EE9DE1E.6060800@redhat.com> Date: Thu, 15 Dec 2011 12:46:38 +0100 From: Kevin Wolf MIME-Version: 1.0 References: <1323892874-13234-1-git-send-email-aliguori@us.ibm.com> <4EE91045.9070109@codemonkey.ws> <4EE98433.9080205@suse.de> <4EE9BEA4.5020004@weilnetz.de> <20111215100412.GB2375@redhat.com> <4EE9CBEC.9030909@weilnetz.de> <4EE9DBC9.4090801@suse.de> In-Reply-To: <4EE9DBC9.4090801@suse.de> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2) List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: =?UTF-8?B?QW5kcmVhcyBGw6RyYmVy?= Cc: Stefan Weil , Anthony Liguori , qemu-devel@nongnu.org, Avi Kivity Am 15.12.2011 12:36, schrieb Andreas F=C3=A4rber: > 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=C3=A4rber: >>>>> 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. Fo= r a >>>>> more polished general-purpose documentation tool you may want to >>>>> look at >>>>> Doxygen. However GTK-Doc has some special code to document the sign= als >>>>> and properties of GTK+ widgets and GObject classes which other tool= s >>>>> 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 unpleasan= t >>> 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 mu= ch >>> 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#a13a3b6850223d2f5a691c6= 18eee54610 >> >> >> (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). >=20 > Hm, the navigation is what I dislike about the doxygen-generated exampl= e: >=20 > http://wiki.qemu.org/docs-internal/ > http://qemu.weilnetz.de/doxygen/ >=20 > doxygen looks to be oriented more towards C++, with a "Class Hierarchy" > that's completely flat. >=20 > 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