DOC: Validate parameter types in docstrings (e.g. str instead of string) (#23165)

Author: Moisan

scripts/tests/test_validate_docstrings.py

@@ -208,7 +208,7 @@ def mode(self, axis, numeric_only):
 
             .. versionchanged:: 0.1.2
 
-        numeric_only : boolean
+        numeric_only : bool
             Sentence ending in period, followed by multiple directives.
 
             .. versionadded:: 0.1.2
@@ -455,6 +455,50 @@ def blank_lines(self, kind):
         """
         pass
 
+    def integer_parameter(self, kind):
+        """
+        Uses integer instead of int.
+
+        Parameters
+        ----------
+        kind : integer
+            Foo bar baz.
+        """
+        pass
+
+    def string_parameter(self, kind):
+        """
+        Uses string instead of str.
+
+        Parameters
+        ----------
+        kind : string
+            Foo bar baz.
+        """
+        pass
+
+    def boolean_parameter(self, kind):
+        """
+        Uses boolean instead of bool.
+
+        Parameters
+        ----------
+        kind : boolean
+            Foo bar baz.
+        """
+        pass
+
+    def list_incorrect_parameter_type(self, kind):
+        """
+        Uses list of boolean instead of list of bool.
+
+        Parameters
+        ----------
+        kind : list of boolean, integer, float or string
+            Foo bar baz.
+        """
+        pass
+
 
 class BadReturns(object):
 
@@ -590,6 +634,18 @@ def test_bad_generic_functions(self, func):
          ('Parameter "kind" description should finish with "."',)),
         ('BadParameters', 'parameter_capitalization',
          ('Parameter "kind" description should start with a capital letter',)),
+        ('BadParameters', 'integer_parameter',
+         ('Parameter "kind" type should use "int" instead of "integer"',)),
+        ('BadParameters', 'string_parameter',
+         ('Parameter "kind" type should use "str" instead of "string"',)),
+        ('BadParameters', 'boolean_parameter',
+         ('Parameter "kind" type should use "bool" instead of "boolean"',)),
+        ('BadParameters', 'list_incorrect_parameter_type',
+         ('Parameter "kind" type should use "bool" instead of "boolean"',)),
+        ('BadParameters', 'list_incorrect_parameter_type',
+         ('Parameter "kind" type should use "int" instead of "integer"',)),
+        ('BadParameters', 'list_incorrect_parameter_type',
+         ('Parameter "kind" type should use "str" instead of "string"',)),
         pytest.param('BadParameters', 'blank_lines', ('No error yet?',),
                      marks=pytest.mark.xfail),
         # Returns tests

scripts/validate_docstrings.py

@@ -464,7 +464,16 @@ def validate_one(func_name):
                 if doc.parameter_type(param)[-1] == '.':
                     param_errs.append('Parameter "{}" type should '
                                       'not finish with "."'.format(param))
-
+                common_type_errors = [('integer', 'int'),
+                                      ('boolean', 'bool'),
+                                      ('string', 'str')]
+                for incorrect_type, correct_type in common_type_errors:
+                    if incorrect_type in doc.parameter_type(param):
+                        param_errs.append('Parameter "{}" type should use '
+                                          '"{}" instead of "{}"'
+                                          .format(param,
+                                                  correct_type,
+                                                  incorrect_type))
         if not doc.parameter_desc(param):
             param_errs.append('Parameter "{}" '
                               'has no description'.format(param))