From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:50213) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rb9dL-0006zK-69 for qemu-devel@nongnu.org; Thu, 15 Dec 2011 06:37:59 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Rb9dG-0004U6-JO for qemu-devel@nongnu.org; Thu, 15 Dec 2011 06:37:55 -0500 Received: from cantor2.suse.de ([195.135.220.15]:45431 helo=mx2.suse.de) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rb9dG-0004Ty-AM for qemu-devel@nongnu.org; Thu, 15 Dec 2011 06:37:50 -0500 Message-ID: <4EE9DBC9.4090801@suse.de> Date: Thu, 15 Dec 2011 12:36:41 +0100 From: =?UTF-8?B?QW5kcmVhcyBGw6RyYmVy?= 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> In-Reply-To: <4EE9CBEC.9030909@weilnetz.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: Stefan Weil Cc: Anthony Liguori , qemu-devel@nongnu.org, Avi Kivity 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. 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 signa= ls >>>> 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 muc= h >> more pleasant to consume. >> >> Regards, >> Daniel >=20 > I think that does not depend on the tools but on the people > who use them. >=20 > The output for the memory API is basically the same with > gtkdoc and doxygen: >=20 > http://wiki.qemu.org/docs-internal/QEMU-Memory-API.html > http://qemu.weilnetz.de/doxygen/memory_8h.html#a13a3b6850223d2f5a691c61= 8eee54610 >=20 >=20 > (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). >=20 > 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 --=20 SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N=C3=BCrnberg, Germany GF: Jeff Hawn, Jennifer Guild, Felix Imend=C3=B6rffer; HRB 16746 AG N=C3=BC= rnberg