DOC: Validate the Returns section in the docstrings

scripts/validate_docstrings.py validates that the content of a docstring follows our standards. There are still some of those standards that the script does not validate, and this gives the users the wrong impression that the docstring is all right, when it’s not really the case. All the missing validations are listed in #20298.

The format of the Returns section consists of a first line with just the type, and afterwards indented the description. In the case a tuple is returned, then the format is name : type or types for each parameter, and indented descriptions after them. The descriptions need to start with a capital letter and finish with a period. See: https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html#section-4-returns-or-yields

For this issue is required:

• Change scripts/validate_docstings.py to give errors if some of the described formats are not satisfied.
• Add tests in scripts/tests/test_validate_docstrings.py

[datapythonista]

In this case it should fail because there is a single value being returned, and it contains the name obj_head.

The correct cases are:

Returns
--------
int
    The single integer value that the function returns.

Returns
--------
id : int
    The function returns a tuple, and the first value is an integer with the id.
name : str
    The second value of the tuple is a string with the name.

[igorfassen]

I’ve added some checks in validate_docstrings.py, and some corresponding tests.

i’ve created the following pull request : #23432

(sorry, i’m not very familiar with github, i hope I’ve done this the right way…)