On Thursday, April 19, 2012 5:21:20 AM UTC-7, Roy Smith wrote: > Let's say I have a function which takes a list of words. I might write > the docstring for it something like: > > def foo(words): > "Foo-ify words (which must be a list)" > > What if I want words to be the more general case of something you can > iterate over? How do people talk about that in docstrings? Do you say > "something which can be iterated over to yield words", "an iterable over > words", or what? > > I can think of lots of ways to describe the concept, but most of them > seem rather verbose and awkward compared to "a list of words", "a > dictionary whose keys are words", etc.
When I talk about an iterable, I say "iterable". Based on my recent readings of the style guide PEPs I would write something like: """Foo-ify some words. Arguments: words -- an iterable of words """ Just remember that types don't matter (until you get down to the C, really), just the methods associated with an object. Have fun and happy coding! -- http://mail.python.org/mailman/listinfo/python-list
