How do you refer to an iterator in docs?

[Cameron Simpson]

On 19Apr2012 18:07, Terry Reedy <tjreedy at udel.edu> wrote:
| On 4/19/2012 5:32 PM, Cameron Simpson wrote:
| > On 19Apr2012 14:32, Terry Reedy<tjreedy at udel.edu>  wrote:
| > | On 4/19/2012 11:51 AM, Jacob MacDonald wrote:
| > |>  When I talk about an iterable, I say "iterable".
| > |
| > | Ditto.
| >
| > I used to, but find myself saying "sequence" these days. It reads
| > better, but is it the same thing?
| 
| A Python 'sequence' is a collection that has a length and can be indexed 
| by counts 0, 1, ... . In other words, len(s) and s[n] work. This 
| definition is in the library manual somewhere.

I think I've failed to find this definition in the past, hence my
misuse. I'll go back to saying "iterable", as that is usually what I
intend.

On the same topic, when I write a generator my docstring tends to come
in one of two forms:

  foo() yields values ...

or

  foo() returns an iterable ...

I find the first clumsy, but tend not to think of generators as "returning"
an iterable as a single action. But of course they do, don't
they: the generator instance itself, since I can say "x = foo()" and
then iterate over "x".

So is the second docstring style better/preferred/more common?

Cheers,
-- 
Cameron Simpson <cs at zip.com.au> DoD#743
http://www.cskk.ezoshosting.com/cs/

The trouble with the rat-race is, even if you win, you're still a rat.
        - James Youngman <JYoungman at vggas.com>