search

terrencepreilly / darglint

A python documentation linter which checks that the docstring description matches the definition.
MIT License
481 stars 41 forks source link

False-positive DAR301 for yielding function/method when using Sphinx-style docstrings #165

Open smithfred opened 3 years ago

smithfred commented 3 years ago

When a function/method uses yield, Darglint outputs an error as follows:

DAR301: foo_function: Missing "Yields" in Docstring: - yield

Though this is correct for e.g. Google-style docstrings, Sphinx itself doesn't support yields as a field name:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#python-signatures

The field names must consist of one of these keywords

(Emphasis mine.)

For Sphinx-style docstrings, the correct format for a yielding function/method AFAICS is:

:returns: (description of returned iterator)

And optionally (if type hints aren't being used):

:rtype: Iterator

terrencepreilly commented 3 years ago

Good catch. I see a lot of use of :yields: in the wild, but if it's not in the spec, then it definitely shouldn't be required. (Although, since others find it convenient, it should at most be a non-default warning to use it.)