How do you refer to an iterator in docs?
Jean-Michel Pichavant
jeanmichel at sequans.com
Fri Apr 20 08:53:00 EDT 2012
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.
More information about the Python-list
mailing list