From: Michal Privoznik <mprivozn@redhat.com>
Date: Mon, 12 May 2014 12:23:18 +0000 (+0200)
Subject: apibuild: Disallow 'returns' return description
X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=0f1a0fff0e29d9eab34f13a1dce9bff9477104d9;p=libvirt.git

apibuild: Disallow 'returns' return description

Our documentation generator is a bit messy, to say the least. For
instance, the description to return values of a function is
searched within C comment. Currently, all lines that start with
'returns' or 'Returns' are viewed as return value description.
However, there are some valid uses where the 'returns' word is in
the middle of a sentence describing function behavior not the
return value. And there are no places where 'returns' is used to
describe return values.  For instance:
virDomainDetachDeviceFlags, virConnectNetworkEventRegisterAny and
virDomainGetDiskErrors. This leads to HTML documemtation being
generated incorrectly.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
---

diff --git a/docs/apibuild.py b/docs/apibuild.py
index 71494d5edd..5250c5ad73 100755
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -926,7 +926,7 @@ class CParser:
                 if i < len(l) and l[i] == ' ':
                     i = i + 1
                 l = l[i:]
-            if len(l) >= 6 and  l[0:7] == "returns" or l[0:7] == "Returns":
+            if len(l) >= 6 and l[0:7] == "Returns":
                 try:
                     l = string.split(l, ' ', 1)[1]
                 except: