If docstring has "Yields" instead of "Returns" annotate as Generator?

[anentropic]

Currently we treat Yields as just an alternate section title and annotate func as -> <type>

This is probably an incorrect annotation

https://mypy.readthedocs.io/en/stable/kinds_of_types.html#generators suggests three options

The simplest would be -> Iterator[<type>]

The more explicit would be -> Generator[<type>, None, None]

[anentropic]

-> Iterator[<type>]

• Pro: More concise
• Pro: Not wrong
• Con: not unambiguously a generator

-> Generator[<type>, None, None]

• Pro: explicitly a generator
• Con: 2nd type (<SendType>) might be wrong (no way to annotate in Napoleon I think)
• Con: 3rd type (<ReturnType>) might be wrong (we could fix by accepting separate Yields and Returns sections in a docstring... does anyone use that though?)

Probably in either case all docstrings with Yields should log a warning so that you can check the annotation and update.

Despite the cons I still lean towards the latter, as it's more explicit. Also if the 2nd and 3rd types are wrong hopefully the type checker would pick up on that, whereas with the former annotation it might pass silently and leave things under-typed (I guess?)