TST/ENH: add default values check to validate_docstrings.py

[josibake]

Problem description

Per contributing_docstring#section-3-parameters, default values should be documented as such:

• int, default 0
• int, default -1, meaning all cpus (optional descriptions)

Currently, the validate_docstrings.py script does not check default values. This should be added to ensure valid docstrings.

Proposal

Add a new validation, "PR11", to the validate_docstrings scripts. "PR03" compares the ordering of the actual arguments to the documented arguments: this might be a good starting point. The validation would need to

• check which params have a default value
• check that the documentation for the parameter has the correct format for default value documentation
• check that the documented value matches the actual value

Questions

• If default values documentation is enforced, does it make sense to allow optional descriptions inline?
• Can it be verified that the parameter description includes the default value description?

[angelaambroz]

✋ I'd be interested in working on this. Should I wait until someone from the core dev team addresses the open questions?

[mroeschke]

Thanks for the request, but it appears this hasn't gain traction in a while so closing