Jon Clements wrote:
On Thursday, 19 April 2012 13:21:20 UTC+1, 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.
I would just write the function signature as (very similar to how itertools
does it):
def func(iterable, ..):
pass
IMHO that documents itself.
If you need explicit, look at the itertools documentation.
hth
Jon.
I think arguments should be named after their content/purpose instead of
their type/nature.
For documenation, argument should mention their type, 'iterable' is a
valid choice.
in other words:
def func(words):
"""func-ify the given iterable of words"
would be better than
def func(iterable):
"""func-ify the given iterable of words"
JM
PS : my point stands valid for the itertools module, as within this
module, an argument purpose could be to be iterable withtout any regard
for the content.
--
http://mail.python.org/mailman/listinfo/python-list
