google / google/styleguide

Python "yields" should be specific about what type is returned

Open
#350 2 comments 0 reactions 1 assignee Claimed by @gpshead View on GitHub
lang:python
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.