Python "yields" should be specific about what type is returned
- Dominant language
- HTML
- Stars
- 39.6k
- Forks
- 12.9k
- Avg merge
- 42m
- Merged PRs (30d)
- 15
Description
The guide on [doc comments](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments) is ambiguous about what type should be documented in the "Yields:" section of a doc comment for a function like this:
```py
def get_words(lines):
""" ... """
for line in lines:
yield line.split()
```
The obvious possibilities are:
1. "Yields: a list of words extracted from an input line."
2. "Yields: a sequence of lists of words extracted from the respective input lines."
3. "Yields: a generator of lists of words extracted from the respective lines."
There should be a clear guide so that "Yields: a sequence of T" can be understood unambiguously as either "each yielded value is a T" or "each yielded value is a sequence of T" as appropriate.
Contributor guide
Assessment
This issue has not been assessed yet.