add inverse check and fix repeated check

numpydoc/tests/test_validate.py

@@ -949,7 +949,7 @@ def bad_parameter_spacing(self, a, b):
 
     def no_documented_optional(self, a=5):
         """
-        Missing optional.
+        Missing optional in docstring.
 
         Parameters
         ----------
@@ -958,6 +958,19 @@ def no_documented_optional(self, a=5):
         """
         pass
 
+    def no_default_when_documented_optional(self, a, b):
+        """
+        Missing default in signature.
+
+        Parameters
+        ----------
+        a : int, optional
+            One way to denote optional.
+        b : int, default 5
+            Another way to denote optional.
+        """
+        pass
+
 
 class BadReturns:
     def return_not_documented(self):
@@ -1397,7 +1410,15 @@ def test_bad_generic_functions(self, capsys, func):
             (
                 "BadParameters",
                 "no_documented_optional",
-                ('Parameter "a" is optional but not documented',),
+                ('Parameter "a" is optional but not documented, or vice versa',),
+            ),
+            (
+                "BadParameters",
+                "no_default_when_documented_optional",
+                (
+                    'Parameter "a" is optional but not documented, or vice versa',
+                    'Parameter "b" is optional but not documented, or vice versa',
+                ),
             ),
             # Returns tests
             ("BadReturns", "return_not_documented", ("No Returns section found",)),

numpydoc/validate.py

@@ -79,7 +79,7 @@
     "PR09": 'Parameter "{param_name}" description should finish with "."',
     "PR10": 'Parameter "{param_name}" requires a space before the colon '
     "separating the parameter name and type",
-    "PR11": 'Parameter "{param_name}" is optional but not documented',
+    "PR11": 'Parameter "{param_name}" is optional but not documented, ' "or vice versa",
     "RT01": "No Returns section found",
     "RT02": "The first line of the Returns section should contain only the "
     "type, unless multiple values are being returned",
@@ -583,7 +583,8 @@ def validate(obj_name):
 
     for param, kind_desc in doc.doc_all_parameters.items():
         if not param.startswith("*"):  # Check can ignore var / kwargs
-            if not doc.parameter_type(param):
+            param_type = doc.parameter_type(param)
+            if not param_type:
                 if ":" in param:
                     errs.append(error("PR10", param_name=param.split(":")[0]))
                 else:
@@ -593,13 +594,19 @@ def validate(obj_name):
                     errs.append(error("PR05", param_name=param))
                 # skip common_type_error checks when the param type is a set of
                 # options
-                if "{" in doc.parameter_type(param):
+                if "{" in param_type:
                     continue
                 common_type_errors = [
                     ("integer", "int"),
                     ("boolean", "bool"),
                     ("string", "str"),
                 ]
+
+                # check that documented optional param has default in sig
+                if "optional" in param_type or "default" in param_type:
+                    if param not in doc.optional_signature_parameters_names:
+                        errs.append(error("PR11", param_name=param))
+
                 for wrong_type, right_type in common_type_errors:
                     if wrong_type in doc.parameter_type(param):
                         errs.append(
@@ -611,13 +618,14 @@ def validate(obj_name):
                             )
                         )
 
-        for param in doc.optional_signature_parameters_names:
-            type = doc.parameter_type(param)
-            if "optional" not in type and "{" not in type and "default" not in type:
-                errs.append(error("PR11", param_name=param))
-
         errs.extend(_check_desc(kind_desc[1], "PR07", "PR08", "PR09", param_name=param))
 
+    # check param with default in sig is documented as optional
+    for param in doc.optional_signature_parameters_names:
+        type = doc.parameter_type(param)
+        if "optional" not in type and "{" not in type and "default" not in type:
+            errs.append(error("PR11", param_name=param))
+
     if doc.is_function_or_method:
         if not doc.returns:
             if doc.method_returns_something: