[libvirt] [PATCH] apibuild: Disallow 'returns' return decription
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 nor the return value. For instance: virDomainDetachDeviceFlags, virConnectNetworkEventRegisterAny and virDomainGetDiskErrors. This leads to HTML documentation to be not correctly generated. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> --- docs/apibuild.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/apibuild.py b/docs/apibuild.py index 71494d5..5250c5a 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: -- 1.9.0
s/decription/description/ in the commit message On 05/12/2014 02:29 PM, Michal Privoznik wrote:
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 nor the return value. For
s/nor/not/ And there are no places where 'returns' is used to describe return values.
instance: virDomainDetachDeviceFlags, virConnectNetworkEventRegisterAny and virDomainGetDiskErrors. This leads to HTML documentation to be not correctly generated.
"to be not" doesn't sound right to me. How about: leads to HTML documemtation being generated incorrectly
Signed-off-by: Michal Privoznik <mprivozn@redhat.com> --- docs/apibuild.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
ACK Jan
On Mon, May 12, 2014 at 02:29:44PM +0200, Michal Privoznik wrote:
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 nor the return value. For instance: virDomainDetachDeviceFlags, virConnectNetworkEventRegisterAny and virDomainGetDiskErrors. This leads to HTML documentation to be not correctly generated.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com> --- docs/apibuild.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/apibuild.py b/docs/apibuild.py index 71494d5..5250c5a 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":
You could've just used l.startswith("Returns"), but more of this would be needed in greater part of the code, right? :) Martin
participants (3)
-
Ján Tomko -
Martin Kletzander -
Michal Privoznik