manual: Improve handling of return type docs

If no documentation is provided for the return value of a function, the
documentation generator will attempt to infer the documentation based on
the return type.

libsel4/tools/syscall_stub_gen.py

@@ -494,6 +494,9 @@ def generate_unmarshal_expressions(params, wordsize):
         results.append((param, unmarshal_single_param(first_bit, num_bits, wordsize)))
     return results
 
+def is_result_struct_required(output_params):
+    return len([x for x in output_params if not x.type.pass_by_reference()]) != 0
+
 def generate_result_struct(interface_name, method_name, output_params):
     """
     Generate a structure definition to be returned by the system call stubs to
@@ -512,7 +515,7 @@ def generate_result_struct(interface_name, method_name, output_params):
     """
 
     # Do we actually need a structure?
-    if len([x for x in output_params if not x.type.pass_by_reference()]) == 0:
+    if not is_result_struct_required(output_params):
         return None
 
     #
@@ -799,12 +802,6 @@ def parse_xml_file(input_file, valid_types):
                 normalised_method_description_text = normalise_text(method_description_text)
                 comment_lines.append("\n@xmlonly\n%s\n@endxmlonly\n" % normalised_method_description_text)
 
-            method_return_description = method.getElementsByTagName("return")
-            if method_return_description:
-                comment_lines.append("@return @xmlonly %s @endxmlonly" % get_xml_element_contents(method_return_description[0]))
-            else:
-                comment_lines.append("@return @xmlonly <errorenumdesc/> @endxmlonly")
-
             #
             # Get parameters.
             #
@@ -843,6 +840,17 @@ def parse_xml_file(input_file, valid_types):
 
                     comment_lines.append("@param[%s] %s %s " % (param_dir, param_name, param_description))
 
+            method_return_description = method.getElementsByTagName("return")
+            if method_return_description:
+                comment_lines.append("@return @xmlonly %s @endxmlonly" % get_xml_element_contents(method_return_description[0]))
+            else:
+                # no return documentation given - default to something sane
+                if is_result_struct_required(output_params):
+                    comment_lines.append("@return @xmlonly @endxmlonly")
+                else:
+                    comment_lines.append("@return @xmlonly <errorenumdesc/> @endxmlonly")
+
+
             # split each line on newlines
             comment_lines = reduce(operator.add, [l.split("\n") for l in comment_lines], [])
 

manual/tools/parse_doxygen_xml.py

@@ -24,6 +24,14 @@ LATEX_ESCAPE_PATTERNS = {
 }
 LATEX_ESCAPE_REGEX = re.compile('|'.join(LATEX_ESCAPE_PATTERNS.keys()))
 
+# Returns the latex doc for the return value of a function
+# implied by its return type
+def default_return_doc(ret_type):
+    if ret_type == "void":
+        return "\\noret"
+
+    return ""
+
 # Return a string with latex special characters escaped
 def latex_escape(string):
     return LATEX_ESCAPE_REGEX.sub(lambda p: LATEX_ESCAPE_PATTERNS[p.group()], string)
@@ -133,13 +141,14 @@ def parse_detailed_desc(parent, ref_dict):
 
             details += parse_para(n, ref_dict)
 
-    ret = "\\noret"
+    ret_str = get_text(parent.getElementsByTagName("type")[0], recur=True, escape=False)
+    ret = default_return_doc(ret_str.split()[-1])
     simplesects = detailed_desc.getElementsByTagName("simplesect")
     for n in simplesects:
         if n.nodeType == xml.dom.Node.ELEMENT_NODE and \
                 n.getAttribute("kind") == "return":
-
             ret = parse_para(n, ref_dict)
+            break
 
     return (details, params_str, ret)
 
@@ -147,7 +156,7 @@ def parse_detailed_desc(parent, ref_dict):
 def parse_prototype(parent):
     inline = parent.getAttribute("inline") == "yes"
     static = parent.getAttribute("static") == "yes"
-    ret_type = get_text(parent.getElementsByTagName("type")[0])
+    ret_type = get_text(parent.getElementsByTagName("type")[0], recur=True)
     name = get_text(parent.getElementsByTagName("name")[0])
 
     output = "%s %s" % (ret_type, name)