| Message ID | 4EE91045.9070109@codemonkey.ws |
|---|---|
| State | New |
| Headers | show |
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 >> Liguori<aliguori@us.ibm.com>wrote: >> >>> 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
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
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
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
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
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
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
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
From f3894f803b417bbfc19d282fda348ff9e0d6ce26 Mon Sep 17 00:00:00 2001 From: Anthony Liguori <aliguori@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>\n<NAME>$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>\n<NAME>$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