pydocstyle: undocumented returns

[adamjstewart]

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 functions
• Yields: 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!

[augustelalande]

This could be part of #458 which hasn't been implemented yet

[dhruvmanila]

Thank you for such a detailed issue! I'll merge this with #458, specifically DAR201 and DAR301 which covers return and yield respectively.