docs: abort when missing return or argument documentation

When a function has no associated information to one of its
arguments or its return type we report it and stop with an error.

diff --git a/docs/apibuild.py b/docs/apibuild.py
index 2d7293639af9532d31b848fbb8c1c9cc7191ee28..e5cbbe8924260ac0af8704cc259359f18d0541de 100755 (executable)
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -1962,12 +1962,17 @@ class docBuilder:
         self.xref = {}
         self.index = {}
         self.basename = name
+        self.errors = 0
 
     def warning(self, msg):
         global warnings
         warnings = warnings + 1
         print msg
 
+    def error(self, msg):
+        self.errors += 1
+        print >>sys.stderr, "Error:", msg
+
     def indexString(self, id, str):
         if str == None:
             return
@@ -2185,6 +2190,8 @@ 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)
                 else:
                     output.write("      <return type='%s' info='%s'/>\n" % (
                              ret[0], escape(ret[1])))
@@ -2192,8 +2199,11 @@ class docBuilder:
             for param in params:
                 if param[0] == 'void':
                     continue
-                if param[2] == None:
-                    output.write("      <arg name='%s' type='%s' info=''/>\n" % (param[1], param[0]))
+                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]))
+                    else:
+                        self.error("Missing documentation for arg `%s' of function `%s'" % (param[1], name))
                 else:
                     output.write("      <arg name='%s' type='%s' info='%s'/>\n" % (param[1], param[0], escape(param[2])))
                     self.indexString(name, param[2])
@@ -2463,6 +2473,10 @@ class docBuilder:
         output.write("</api>\n")
         output.close()
 
+        if self.errors > 0:
+            print >>sys.stderr, "apibuild.py: %d error(s) encountered during generation" % self.errors
+            sys.exit(3)
+
         filename = "%s/%s-refs.xml" % (self.path, self.name)
         if not quiet:
             print "Saving XML Cross References %s" % (filename)