DOCS: Adopt the numpydoc validation rules

[tkknight]

📚 Documentation

The pre-commit hook to check these rules was added in https://github.com/SciTools/iris/pull/5762.

The outstanding rules review and ideally adoption are below as defined in pyproject.toml (section [tool.numpydoc_validation]). There is an option to keep them ignored only it absolutely needed.

• [ ] GL08 The object does not have a docstring : 1320 errors
• [ ] PR01 Parameters ... not documented : 951 errors
• [ ] PR02 Unknown parameters {....} - 74 errors
• [ ] PR04 Parameter "...." has no type : 407 errors
• [ ] PR07 Parameter "...." has no description : 47 errors
• [ ] RT01 No Returns section found : 609 errors
• [ ] RT03 Return value has no description : 219 errors

To test these rules just comment out one at a time and then run the pre-commit locally via pre-commit run --all-files.

For more information see https://numpydoc.readthedocs.io/en/latest/validation.html.

See also #5625 ruff: incremental adoption.