[libvirt] [PATCH v3 06/13] docs: only generate function argument info for args with a description

Claudio Bley cbley at av-test.de
Fri Feb 1 13:24:58 UTC 2013


At Fri, 01 Feb 2013 13:48:45 +0100,
Claudio Bley wrote:
> 
> At Thu, 31 Jan 2013 13:41:10 -0700,
> Eric Blake wrote:
> > 
> > On 01/30/2013 08:38 AM, Claudio Bley wrote:
> > > When function arguments or return values lack a description there's no
> > > use in generating a meaningless "ARG1: " stanza.
> > 
> > Can you point to an example of an argument lacking a description? 
> 
> Have a look at e.g. #virEventUpdateHandle

I just realized that this patch doesn't work anymore because I lost
track of the original goal of not writing out empty info attributes
for function
arguments. (https://www.redhat.com/archives/libvir-list/2013-January/msg01537.html)

Certainly because I figured it would not make sense anymore because we
would bail out with an error if anything is missing.

But then, I skipped the /ignored/ functions which re-introduced the
empty info attributes in libvirt-api.xml.

You need to squash this in prior before this has any effect.

---- >8 ----
diff --git a/docs/apibuild.py b/docs/apibuild.py
index e5cbbe8..60e3b4a 100755
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -2190,8 +2190,11 @@ class docBuilder:
             if ret[0] != None:
                 if ret[0] == "void":
                     output.write("      <return type='void'/>\n")
-                elif (ret[1] == None or ret[1] == '') and not ignored_functions.has_key(name):
-                    self.error("Missing documentation for return of function `%s'" % name)
+                elif (ret[1] == None or ret[1] == ''):
+                    if ignored_functions.has_key(name):
+                        output.write("      <return type='%s'/>\n" % ret[0])
+                    else:
+                        self.error("Missing documentation for return of function `%s'" % name)
                 else:
                     output.write("      <return type='%s' info='%s'/>\n" % (
                              ret[0], escape(ret[1])))
@@ -2201,7 +2204,7 @@ class docBuilder:
                     continue
                 if (param[2] == None or param[2] == ''):
                     if ignored_functions.has_key(name):
-                        output.write("      <arg name='%s' type='%s' info=''/>\n" % (param[1], param[0]))
+                        output.write("      <arg name='%s' type='%s'/>\n" % (param[1], param[0]))
                     else:
                         self.error("Missing documentation for arg `%s' of function `%s'" % (param[1], name))
                 else:




More information about the libvir-list mailing list