DOC: add checks on the returns section in the docstrings (#23138)

Author: igorfassen

scripts/tests/test_validate_docstrings.py

@@ -545,6 +545,30 @@ 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 descriptions.
+
+        Returns
+        -------
+        foo : str
+           the first returned string.
+        bar : str
+           the second returned string.
+        """
+        return "Hello", "World!"
+
 
 class BadSeeAlso(object):
 
@@ -696,10 +720,18 @@ def test_bad_generic_functions(self, 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',
+         ('No name is to be provided when returning a single value',)),
+        ('BadReturns', 'no_capitalization',
+         ('Return value "foo" description should start with a capital '
+          'letter',)),
+        ('BadReturns', 'no_capitalization',
+         ('Return value "bar" description should start with a capital '
+          'letter',)),
         # See Also tests
         ('BadSeeAlso', 'prefix_pandas',
          ('pandas.Series.rename in `See Also` section '

scripts/validate_docstrings.py

@@ -491,8 +491,34 @@ def validate_one(func_name):
             errs.append('\t{}'.format(param_err))
 
     if doc.is_function_or_method:
-        if not doc.returns and "return" in doc.method_source:
-            errs.append('No Returns section found')
+        if not doc.returns:
+            if "return" in doc.method_source:
+                errs.append('No Returns section found')
+        else:
+            returns_errs = []
+            if len(doc.returns) == 1 and doc.returns[0][1]:
+                returns_errs.append('No name is to be provided when '
+                                    'returning a single value.')
+            for name, type_, desc in doc.returns:
+                desc = ''.join(desc)
+                name = '"' + name + '" ' if type_ else ''
+                if not desc:
+                    returns_errs.append('Return value {}has no '
+                                        'description'.format(name))
+                else:
+                    if not desc[0].isupper():
+                        returns_errs.append('Return value {}description '
+                                            'should start with a capital '
+                                            'letter'.format(name))
+                    if desc[-1] != '.':
+                        returns_errs.append('Return value {}description '
+                                            'should finish with '
+                                            '"."'.format(name))
+            if returns_errs:
+                errs.append('Errors in returns section')
+                for returns_err in returns_errs:
+                    errs.append('\t{}'.format(returns_err))
+
         if not doc.yields and "yield" in doc.method_source:
             errs.append('No Yields section found')