[rr-]

Returns and yields both parse into DocstringReturns, and Docstring.returns took the first DocstringReturns it found. A generator's docstring then looked like it documented a return value:

>>> docstring = parse("Short.\n\nYields:\n    int: The next number.")
>>> docstring.returns.description   # before
'The next number.'
>>> docstring.returns               # now
None
>>> docstring.yields.description
'The next number.'

returns and many_returns now leave out metas whose kind is Kind.YIELDS. The new yields and many_yields give those instead. The class stays DocstringReturns and is_generator stays, so code that reads yields through meta keeps working.

This is breaking for users who read yields through returns. They need to switch to yields. pydoclint's fork has yields and many_yields under these names, so code written against the fork works with this.

Parse output does not change, so parity is 0 of 29,074. The change is only in what the two properties return. A yield shows up in some style for 9 case inputs, 4 stdlib docstrings and 2,454 generated ones, and those are the docstrings where returns can now give something else.

Bench on 3.8: 0.99–1.03x of main.