RT02 enforces the pandas docstring guide, not the numpydoc docstring guide
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
The RT02 error has the description:
"The first line of the Returns section should contain only the type, unless multiple values are being returned"
This appears to enforce the pandas docstring guide:
"...no name will be provided, unless the method returns or yields more than one value"
In contrast, the numpydoc docstring guide states:
"...the name of each return value is optional. The type of each return value is always required"
This is a concern for SciPy, where the general standard has been to specify the name of all return values, even when only a single value is returned. As a very rough measure, over 42% of the functions in scipy.stats are currently tripping RT02 errors (and that's without bothering to bracket out the functions which return multiple values).
Possible solutions:
-
Update the numpydoc docstring guide to stipulate what RT02 enforces. This would necessitate a lot of little edits (at least for SciPy) and the loss of some potentially valuable information from the documentation.
-
Remove RT02 from
numpydoc.validate. But then, pandas either loses that particular validation or has to (re)implement a version of the script in their project, which would be a reversal of the recent effort to bring things from pandas to numpydoc. -
Or, as a compromise, demote RT02 to a warning, which would only report if specifically requested. If numpydoc doesn't mind maintaining non-numpydoc warnings, a central collection would be convenient for numpydoc users looking for stricter validation. Further, if there is a desire to update the numpydoc docstring guide, collaborating about such warnings would be a great place to start.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with RT02 in numpydoc/validate.py and read the linked numpydoc and pandas guidance. Review the three proposed resolutions and the existing discussion before choosing a project decision; done means the validator behavior and documented standard agree, with any selected warning behavior applied consistently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100