diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py index 3d16fecb4ec3c..bb58449843096 100644 --- a/scripts/tests/test_validate_docstrings.py +++ b/scripts/tests/test_validate_docstrings.py @@ -633,6 +633,43 @@ def no_punctuation(self): """ return "Hello world!" + def named_single_return(self): + """ + Provides name but returns only one value. + + Returns + ------- + s : str + A nice greeting. + """ + return "Hello world!" + + def no_capitalization(self): + """ + Forgets capitalization in return values description. + + Returns + ------- + foo : str + The first returned string. + bar : str + the second returned string. + """ + return "Hello", "World!" + + def no_period_multi(self): + """ + Forgets period in return values description. + + Returns + ------- + foo : str + The first returned string + bar : str + The second returned string. + """ + return "Hello", "World!" + class BadSeeAlso(object): @@ -829,10 +866,18 @@ def test_bad_generic_functions(self, capsys, func): ('BadReturns', 'yield_not_documented', ('No Yields section found',)), pytest.param('BadReturns', 'no_type', ('foo',), marks=pytest.mark.xfail), - pytest.param('BadReturns', 'no_description', ('foo',), - marks=pytest.mark.xfail), - pytest.param('BadReturns', 'no_punctuation', ('foo',), - marks=pytest.mark.xfail), + ('BadReturns', 'no_description', + ('Return value has no description',)), + ('BadReturns', 'no_punctuation', + ('Return value description should finish with "."',)), + ('BadReturns', 'named_single_return', + ('The first line of the Returns section should contain only the ' + 'type, unless multiple values are being returned',)), + ('BadReturns', 'no_capitalization', + ('Return value description should start with a capital ' + 'letter',)), + ('BadReturns', 'no_period_multi', + ('Return value description should finish with "."',)), # Examples tests ('BadGenericDocStrings', 'method', ('Do not import numpy, as it is imported automatically',)), diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index bfc52a0de918b..4e389aed2b0d2 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -105,6 +105,11 @@ 'PR10': 'Parameter "{param_name}" requires a space before the colon ' 'separating the parameter name and type', 'RT01': 'No Returns section found', + 'RT02': 'The first line of the Returns section should contain only the ' + 'type, unless multiple values are being returned', + 'RT03': 'Return value has no description', + 'RT04': 'Return value description should start with a capital letter', + 'RT05': 'Return value description should finish with "."', 'YD01': 'No Yields section found', 'SA01': 'See Also section not found', 'SA02': 'Missing period at end of description for See Also ' @@ -685,8 +690,22 @@ def get_validation_data(doc): errs.append(error('PR09', param_name=param)) if doc.is_function_or_method: - if not doc.returns and 'return' in doc.method_source: - errs.append(error('RT01')) + if not doc.returns: + if 'return' in doc.method_source: + errs.append(error('RT01')) + else: + if len(doc.returns) == 1 and doc.returns[0][1]: + errs.append(error('RT02')) + for name_or_type, type_, desc in doc.returns: + if not desc: + errs.append(error('RT03')) + else: + desc = ' '.join(desc) + if not desc[0].isupper(): + errs.append(error('RT04')) + if not desc.endswith('.'): + errs.append(error('RT05')) + if not doc.yields and 'yield' in doc.method_source: errs.append(error('YD01'))