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))