Review DOC404 / DOC405 (Generator vs Iterator)

[llucax]

The rule imposed by DOC404/DOC405, including the justification in Notes on Generator vs Iterator doesn't go in line with Python's official documentation, which explicitly says Iterator and AsyncIterator can be used as return types for functions that yield (even more, the documentation say that also Iterable/AsyncIterable can be used).

Having this (artificial) restriction in pydoclint only makes users have to write more pedantic code, which is also harder to read for the casual reader (what are all the None in Generator?), when the shorter form is supported by Python and type-checkers like mypy and pyright.

[jsh9]

Hi @llucax , you convinced me.

I implemented #77 to stop enforcing people to use Generators.

And to address the corner case where a function both yields and returns stuff, I implemented #78, as well as 3 other PRs from another library:

• Parse yields section in docstring docstring_parser_fork#2
• Make "Yields" an official parsed section docstring_parser_fork#3
• Add "many_yields" property docstring_parser_fork#4

Please try out version 0.3.0 (or above). If you find any issues, please don't hesitate to leave other comments!

[llucax]

Thanks @jsh9, I really appreciate it! We are finally switching all our projects to pydoclint ❤️

[jsh9]

Glad to hear that! Thank you for making all these suggestions and providing me test cases!