Patchwork [v2,0/4] GTK-DOC build integration (v2)

login
register
mail settings
Submitter Anthony Liguori
Date Dec. 14, 2011, 9:08 p.m.
Message ID <4EE91045.9070109@codemonkey.ws>
Download mbox | patch
Permalink /patch/131473/
State New
Headers show

Comments

Anthony Liguori - Dec. 14, 2011, 9:08 p.m.
On 12/14/2011 02:54 PM, Marc-André Lureau wrote:
> Hi
>
> 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 "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
>
Andreas Färber - Dec. 15, 2011, 5:22 a.m.
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
Stefan Weil - Dec. 15, 2011, 9:32 a.m.
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
Daniel P. Berrange - Dec. 15, 2011, 10:04 a.m.
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
Kevin Wolf - Dec. 15, 2011, 10:21 a.m.
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
Stefan Weil - Dec. 15, 2011, 10:29 a.m.
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
Andreas Färber - Dec. 15, 2011, 11:36 a.m.
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
Kevin Wolf - Dec. 15, 2011, 11:46 a.m.
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
Stefan Weil - Dec. 18, 2011, noon
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

Patch

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