[issue11889] 'enumerate' 'start' parameter documentation is confusing

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

Note: 3.x correct gives the signature at enumerate(iterable, start) rather that enumerate(sequence, start).

I agree that the current entry is a bit awkward. Perhaps the doc would be clearer with a reference to zipping. Removing the unneeded definition of *iterable* (which should be linked to the definition in the glossary, along with *iterator*), my suggestion is:
'''
enumerate(iterable, start=0)
Return an enumerate object, an *iterator* of tuples, that zips together a sequence of counts and *iterable*. Each tuple contain a count and an item from *iterable*, in that order. The counts begin with *start*, which defaults to 0. enumerate() is useful for obtaining an indexed series: enumerate(seq) produces (0, seq[0]), (1, seq[1]), (2, seq[2]), .... For another example, which uses *start*:

>>> for i, season in enumerate(['Spring','Summer','Fall','Winter'], 1):
...     print(i, season)
1 Spring
2 Summer
3 Fall
4 Winter
'''
Note that I changed the example to use a start of 1 instead of 0, to produce a list in traditional form, which is one reason to have the parameter!

----------
nosy: +terry.reedy
versions: +Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11889>
_______________________________________