From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:35545) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rb8Zd-0006vn-UC for qemu-devel@nongnu.org; Thu, 15 Dec 2011 05:30:07 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Rb8ZY-0007Je-NM for qemu-devel@nongnu.org; Thu, 15 Dec 2011 05:30:01 -0500 Received: from v220110690675601.yourvserver.net ([78.47.199.172]:53833) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rb8ZY-0007JP-Ii for qemu-devel@nongnu.org; Thu, 15 Dec 2011 05:29:56 -0500 Message-ID: <4EE9CBEC.9030909@weilnetz.de> Date: Thu, 15 Dec 2011 11:29:00 +0100 From: Stefan Weil 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> In-Reply-To: <20111215100412.GB2375@redhat.com> Content-Type: text/plain; charset=UTF-8; format=flowed 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: "Daniel P. Berrange" Cc: Avi Kivity , Anthony Liguori , qemu-devel@nongnu.org, =?UTF-8?B?QW5kcmVhcyBGw6RyYmVy?= 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 signal= s >>> 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#a13a3b6850223d2f5a691c618e= ee54610 (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