Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
Anthony Liguori writes: [...] For v2, I'm relying on a fork of gtk-doc that removes the underscore requirements. I really hate to do this but I like it better than not having documentation. I'm poking in the gtk+ community to see if there's an upstream compromise possible. I don't want to start any kind of flame, but did you consider the possibility of using doxygen instead? From my experience, it's pretty complete and also contains all kinds of predefined keywords for documenting pre/post-conditions, notes, warnings, etc. Besides, it offers the possibility to document things separately from the code (e.g., auto-generated structures, or elements declared differently depending on defines), which I was unable to do with some quick tests I had with gtkdoc. Lluis -- And it's much the same thing with knowledge, for whenever you learn something new, the whole world becomes that much richer. -- The Princess of Pure Reason, as told by Norton Juster in The Phantom Tollbooth
Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
Am 15.12.2011 11:21, schrieb Kevin Wolf: Am 15.12.2011 10:32, schrieb Stefan Weil: 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 only modified the first lines of memory.h to get the global C functions, but of course more changes are needed if we choose doxygen as our standard. You seem to have included Anthony's patches (specifically the one to split out nested structs). Is Doxygen really as broken as gtk-doc seems to be or can we do without it? Kevin Yes, the previous results were based on QEMU with Anthony's latest gtkdoc patches. Here is the result from unpatched QEMU code: http://qemu.weilnetz.de/doxygen2/ or http://qemu.weilnetz.de/doxygen2/memory_8h.html I had to remove most graphics because they needed more than 1 GB disk space and filled all available space on my server. Regards, Stefan
Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
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 only modified the first lines of memory.h to get the global C functions, but of course more changes are needed if we choose doxygen as our standard. Regards, Stefan Weil
Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
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 -- |: http://berrange.com -o-http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|
Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
Am 15.12.2011 10:32, schrieb Stefan Weil: 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 only modified the first lines of memory.h to get the global C functions, but of course more changes are needed if we choose doxygen as our standard. You seem to have included Anthony's patches (specifically the one to split out nested structs). Is Doxygen really as broken as gtk-doc seems to be or can we do without it? Kevin
Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
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). 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
Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
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
Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
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
[Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
This series integrates GTK-DOC into our build process via a gtkdoc build target. This is to provide internal API documentation in a more accessible format. Once this gets merged into the tree, I'll add a nightly cron job on qemu.org so that there is always a copy of the latest internal API documentation on the website. I've posted the output of already on qemu.org at: http://wiki.qemu.org/docs-internal/ All it takes to add to this is to submit a patch converting a file to use gtk-doc syntax and then move the header into include/ For more information on gtk-doc, see: http://developer.gnome.org/gtk-doc-manual/unstable/ For v2, I'm relying on a fork of gtk-doc that removes the underscore requirements. I really hate to do this but I like it better than not having documentation. I'm poking in the gtk+ community to see if there's an upstream compromise possible. Anthony Liguori (4): memory: make memory API parsable by gtkdoc-scan (v2) docs: add build infrastructure for gtkdocs (v2) memory: update documentation to be in gtk-doc format memory: move header into include/ and add to QEMU docs Makefile |6 +- Makefile.docs| 29 +++ Makefile.hw |1 + Makefile.target |1 + QEMU-docs.xml| 32 +++ include/memory.h | 566 ++ memory.h | 522 - 7 files changed, 634 insertions(+), 523 deletions(-) create mode 100644 Makefile.docs create mode 100644 QEMU-docs.xml create mode 100644 include/memory.h delete mode 100644 memory.h -- 1.7.4.1
Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
Hi On Wed, Dec 14, 2011 at 9:01 PM, Anthony Liguori aligu...@us.ibm.comwrote: For v2, I'm relying on a fork of gtk-doc that removes the underscore requirements. I really hate to do this but I like it better than not having documentation. I'm poking in the gtk+ community to see if there's an upstream compromise possible. Can you point out a discussion/bug, What is the underscode requirements? thanks -- Marc-André Lureau
Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
On 12/14/2011 02:54 PM, Marc-André Lureau wrote:
Hi
On Wed, Dec 14, 2011 at 9:01 PM, Anthony Liguorialigu...@us.ibm.comwrote:
For v2, I'm relying on a fork of gtk-doc that removes the underscore
requirements. I really hate to do this but I like it better than not
having
documentation. I'm poking in the gtk+ community to see if there's an
upstream
compromise possible.
Can you point out a discussion/bug, What is the underscode requirements?
The following is what I need to make it work. I'm still trying to find out
where to even have this discussion.
Regards,
Anthony Liguori
thanks
From f3894f803b417bbfc19d282fda348ff9e0d6ce26 Mon Sep 17 00:00:00 2001
From: Anthony Liguori aligu...@us.ibm.com
Date: Wed, 14 Dec 2011 13:23:12 -0600
Subject: [PATCH] Don't assume struct names are prefixed with '_'.
---
gtkdoc-mkdb.in |4 ++--
gtkdoc-scan.in | 18 +-
2 files changed, 11 insertions(+), 11 deletions(-)
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index 339203e..096266d 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -1489,7 +1489,7 @@ sub OutputStruct {
my $decl_out = ;
if ($declaration =~ m/^\s*$/) {
#print Found opaque struct: $symbol\n;
-$decl_out = typedef struct _$symbol $symbol;;
+$decl_out = typedef struct _?$symbol $symbol;;
} elsif ($declaration =~ m/^\s*struct\s+\w+\s*;\s*$/) {
#print Found opaque struct: $symbol\n;
$decl_out = struct $symbol;;
@@ -1535,7 +1535,7 @@ sub OutputStruct {
# empty struct declaration.
if ($decl_out eq ) {
if ($has_typedef) {
-$decl_out = typedef struct _$symbol $symbol;;
+$decl_out = typedef struct _?$symbol $symbol;;
} else {
$decl_out = struct $symbol;;
}
diff --git a/gtkdoc-scan.in b/gtkdoc-scan.in
index 04bfb4a..b435a20 100755
--- a/gtkdoc-scan.in
+++ b/gtkdoc-scan.in
@@ -461,7 +461,7 @@ sub ScanHeader {
# ENUMS
-} elsif (s/^\s*enum\s+_(\w+)\s+\{/enum $1 {/) {
+} elsif (s/^\s*enum\s+_?(\w+)\s+\{/enum $1 {/) {
# We assume that 'enum _enum_name {' is really the
# declaration of enum enum_name.
$symbol = $1;
@@ -483,7 +483,7 @@ sub ScanHeader {
# STRUCTS AND UNIONS
-} elsif (m/^\s*typedef\s+(struct|union)\s+_(\w+)\s+\2\s*;/) {
+} elsif (m/^\s*typedef\s+(struct|union)\s+_?(\w+)\s+\2\s*;/) {
# We've found a 'typedef struct _name name;'
# This could be an opaque data structure, so we output an
# empty declaration. If the structure is actually found that
@@ -492,11 +492,11 @@ sub ScanHeader {
@TRACE@($structsym typedef: $2);
$forward_decls{$2} = $structsym\nNAME$2/NAME\n$deprecated/$structsym\n
-} elsif (m/^\s*(?:struct|union)\s+_(\w+)\s*;/) {
+} elsif (m/^\s*(?:struct|union)\s+_?(\w+)\s*;/) {
# Skip private structs/unions.
@TRACE@(private struct/union);
-} elsif (m/^\s*(struct|union)\s+(\w+)\s*;/) {
+} elsif (m/^\s*(struct|union)\s+_?(\w+)\s*;/) {
# Do a similar thing for normal structs as for typedefs above.
# But we output the declaration as well in this case, so we
# can differentiate it from a typedef.
@@ -504,7 +504,7 @@ sub ScanHeader {
@TRACE@($structsym: $2);
$forward_decls{$2} = $structsym\nNAME$2/NAME\n$_$deprecated/$structsym\n;
-} elsif (m/^\s*typedef\s+(struct|union)\s*\w*\s*{/) {
+} elsif (m/^\s*typedef\s+(struct|union)\s*_?\w*\s*{/) {
$symbol = ;
$decl = $_;
$level = 0;
@@ -659,11 +659,11 @@ sub ScanHeader {
# STRUCTS
-} elsif (m/^\s*struct\s+_(\w+)\s*\*/) {
+} elsif (m/^\s*struct\s+_?(\w+)\s*\*/) {
# Skip 'struct _struct_name *', since it could be a
# return type on its own line.
-} elsif (m/^\s*struct\s+_(\w+)/) {
+} elsif (m/^\s*struct\s+_?(\w+)/) {
# We assume that 'struct _struct_name' is really the
# declaration of struct struct_name.
$symbol = $1;
@@ -676,9 +676,9 @@ sub ScanHeader {
# UNIONS
-} elsif (m/^\s*union\s+_(\w+)\s*\*/) {
+} elsif (m/^\s*union\s+_?(\w+)\s*\*/) {
# Skip 'union _union_name *' (see above)
-} elsif (m/^\s*union\s+_(\w+)/) {
+} elsif (m/^\s*union\s+_?(\w+)/) {
$symbol = $1;
$decl = $_;
$level = 0;
--
1.7.4.1
Re: [Qemu-devel] [PATCH v2 0/4] GTK-DOC build integration (v2)
Am 14.12.2011 22:08, schrieb Anthony Liguori: On 12/14/2011 02:54 PM, Marc-André Lureau wrote: On Wed, Dec 14, 2011 at 9:01 PM, Anthony Liguorialigu...@us.ibm.comwrote: For v2, I'm relying on a fork of gtk-doc that removes the underscore requirements. I really hate to do this but I like it better than not having documentation. I'm poking in the gtk+ community to see if there's an upstream compromise possible. Can you point out a discussion/bug, What is the undersco[r]e requirements? The following is what I need to make it work. I'm still trying to find out where to even have this discussion. 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 -- SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Jeff Hawn, Jennifer Guild, Felix Imendörffer; HRB 16746 AG Nürnberg
