pydocstyle: undocumented returns
adamjstewart opened this issue · comments
Feature Request
I would like to propose a new pydocstyle rule that checks for undocumented return values.
Implementation
Specifically, ruff would check to see if a function is missing one of the following sections (assuming Google-style):
Returns:
for normal functionsYields:
for generators
According to the Google Python Style Guide:
If the function only returns None, this section is not required. It may also be omitted if the docstring starts with “Return”, “Returns”, “Yield”, or “Yields”
In the case where the return type of the function is not None
and none of the above criteria are met, a rule violation should be issued.
Rationale
The Google Python Style Guide and the NumPy Style Guide both explicitly require return values to be documented.
Additional Information
The only related feature request I could find in the pydocstyle repo is PyCQA/pydocstyle#479. However, their criteria for whether or not a return value should be documented is whether or not an Args:
section is present. I think checking the return type is much more reliable though.
If this is something ruff would be willing to accept, I can try my hand at following https://docs.astral.sh/ruff/contributing/#example-adding-a-new-lint-rule and submit a PR!
This could be part of #458 which hasn't been implemented yet
Thank you for such a detailed issue! I'll merge this with #458, specifically DAR201
and DAR301
which covers return
and yield
respectively.