pydoclint: Google style: Allow omitting only the `Returns`/`Yields` if summary starts with `Return(s)/Yield(s)`
Google coding style says about the Returns section:
It may also be omitted if the docstring starts with Returns or Yields (e.g. “”“Returns row from Bigtable as a tuple of strings.”“”) and the opening sentence is sufficient to describe the return value.
For now this can be achieved by using the –skip-checking-short-docstrings but it is not exactly the same, as by using this option Args, Raises and other sections are also not required, which an lead to a lot of unintended missing documentation.
It would be good to have an option to make pydoclint explicitly support this exception allowed by the Google style (and make it default to enabled when google style is used).
About this issue
- Original URL
- State: open
- Created 6 months ago
- Comments: 16 (16 by maintainers)
Hi @llucax , I think this is a good idea, and I’ll implement it.
However, there’s one nuance: pydocstyle and subsequently Ruff check the writing style of docstrings, and there will be a
Dviolation if the initial word of a docstring follows the “third-person singular present tense” rule. For example:(There is an “s” at the end of “Calculates”.)
Instead, pydoclint requires people to write in imperative mood:
(Note: there is no “s” at the end of “Calculate”.)
Since pydocstyle is very widely used, I think in my implementation, the criterion of omitting the
Returns/Yieldssection will be: if the initial word of a docstring is return/Return/yield/Yield (note: no “s”).