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 71494d5edd9fc1c40eb2e30d2139a307b0710455..5250c5ad730e7f7dcfbb72cc7eda4a3ceb16d99c 100755 (executable)
--- 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: