R. David Murray added the comment: I think you misunderstand the purpose of the documentation you are suggesting modifying. It is a *reference guide*, and as such it needs to be technically precise and *must* correctly use the "jargon" of the language. Especially since it also functions as the reference guide for people who implement new versions of Python, and need to know what behavior of things like 'enumerate' they need to reproduce.
That said, we also prefer the reference docs to be clear and understandable to someone who is a relative beginner, as long as we don't lose precision in doing so. Thus the glossary and the glossary links, so yes it would be a good idea to add those. I did indeed misspell iterable. Your sentence is still incorrect...items returned by an iterator do not necessarily have an index (that is, you can't say myiterator[3] in the general case). So, if I understand correctly, your difficulty was the confusion between the argument name *sequence* and the technical term ``sequence`` (referring to a Python object type). I agree that that makes things confusing. It would be better if the argument were named *iterable*, but we can't really change it at this point for backward compatibility reasons. Maybe if we rearrange things a bit we can make it clearer. How about this: Return an enumerate object which when iterated[link to glossary] yields a two-tuple for each element in *sequence*, each tuple consisting of the sequence number of the element (beginning with *start*, which defaults to 0) paired with the element itself. *sequence* must be a sequence, an iterator, or some other object which supports iteration. That moves the distracting precise definition of *sequence* to the end, after you've already grasped what the function does. You will note that I've also dropped the reference to next; that is implicit in the mention of "when iterated", since it is an integral part of the iteration protocol. IMO it is a distraction to mention next in this context. It confuses the beginner and isn't needed by the expert. ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue22725> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
