79
79
"PR09" : 'Parameter "{param_name}" description should finish with "."' ,
80
80
"PR10" : 'Parameter "{param_name}" requires a space before the colon '
81
81
"separating the parameter name and type" ,
82
+ "PR11" : 'Parameter "{param_name}" is optional but not documented' ,
82
83
"RT01" : "No Returns section found" ,
83
84
"RT02" : "The first line of the Returns section should contain only the "
84
85
"type, unless multiple values are being returned" ,
@@ -294,17 +295,6 @@ def doc_all_parameters(self):
294
295
295
296
@property
296
297
def signature_parameters (self ):
297
- def add_stars (param_name , info ):
298
- """
299
- Add stars to *args and **kwargs parameters
300
- """
301
- if info .kind == inspect .Parameter .VAR_POSITIONAL :
302
- return f"*{ param_name } "
303
- elif info .kind == inspect .Parameter .VAR_KEYWORD :
304
- return f"**{ param_name } "
305
- else :
306
- return param_name
307
-
308
298
if inspect .isclass (self .obj ):
309
299
if hasattr (self .obj , "_accessors" ) and (
310
300
self .name .split ("." )[- 1 ] in self .obj ._accessors
@@ -317,19 +307,46 @@ def add_stars(param_name, info):
317
307
# Some objects, mainly in C extensions do not support introspection
318
308
# of the signature
319
309
return tuple ()
310
+ params = dict (sig .parameters )
311
+
312
+ if params :
313
+ first_param = next (iter (params .keys ()))
314
+ if first_param in ("self" , "cls" ):
315
+ del params [first_param ]
320
316
321
- params = tuple (
322
- add_stars (parameter , sig .parameters [parameter ])
323
- for parameter in sig .parameters
324
- )
325
- if params and params [0 ] in ("self" , "cls" ):
326
- return params [1 :]
327
317
return params
328
318
319
+ @staticmethod
320
+ def _add_stars (param_name , info ):
321
+ """
322
+ Add stars to *args and **kwargs parameters
323
+ """
324
+ if info .kind == inspect .Parameter .VAR_POSITIONAL :
325
+ return f"*{ param_name } "
326
+ elif info .kind == inspect .Parameter .VAR_KEYWORD :
327
+ return f"**{ param_name } "
328
+ else :
329
+ return param_name
330
+
331
+ @property
332
+ def signature_parameters_names (self ):
333
+ return tuple (
334
+ self ._add_stars (param , info )
335
+ for param , info in self .signature_parameters .items ()
336
+ )
337
+
338
+ @property
339
+ def optional_signature_parameter_names (self ):
340
+ return tuple (
341
+ self ._add_stars (param , info )
342
+ for param , info in self .signature_parameters .items ()
343
+ if info .default is not inspect ._empty
344
+ )
345
+
329
346
@property
330
347
def parameter_mismatches (self ):
331
348
errs = []
332
- signature_params = self .signature_parameters
349
+ signature_params = self .signature_parameters_names
333
350
all_params = tuple (param .replace ("\\ " , "" ) for param in self .doc_all_parameters )
334
351
missing = set (signature_params ) - set (all_params )
335
352
if missing :
@@ -593,6 +610,12 @@ def validate(obj_name):
593
610
wrong_type = wrong_type ,
594
611
)
595
612
)
613
+
614
+ for param in doc .optional_signature_parameter_names :
615
+ type = doc .parameter_type (param )
616
+ if "optional" not in type and "{" not in type and "default" not in type :
617
+ errs .append (error ("PR11" , param_name = param ))
618
+
596
619
errs .extend (_check_desc (kind_desc [1 ], "PR07" , "PR08" , "PR09" , param_name = param ))
597
620
598
621
if doc .is_function_or_method :
0 commit comments