[Numpy-discussion] Docstring standard: how to specify variable types

Robert Kern robert.kern@gmail....
Thu Jan 24 13:15:13 CST 2008


Stefan van der Walt wrote:
> Hi Charles
> 
> On Wed, Jan 23, 2008 at 09:34:44AM -0700, Charles R Harris wrote:
>>     2. How do we specify default values?
>>
>> I like to put them first in the list: {-1, integer}
> 
> When exactly is this list used?  That should be made clear in the
> standard as well.

No special processing is done. I omit it. If I need to talk about the default 
value, I do it in prose in the argument's description. Note that the default 
value is not always the same thing as the value in the signature, particularly 
when kwd=None. But in those cases, I usually need a sentence to describe what's 
happening, so that's where I always put that information.

>>     3. Why do we need the "optional" keyword (the function signature
>>       already indicates that the parameter is optional).
>>
>> It's extra information, true, but that isn't always a bad thing. It's like
>> looking up "whole numbers" in a book index and, instead of the page reference,
>> the index directs you to "numbers, whole". Flip, flip, flip. Drives me crazy.
>> Besides, the function signature might be missing.
> 
> When would the function signature be missing?  In C functions we copy
> the signature into the docstring.  I am concerned about duplicating
> information that may change.
> 
>>     4. Do we really need the "Other Parameters" list?  It would make more
>>       sense to split positional and keyword arguments, but I'm not even
>>       sure that is necessary, since that information is already specified in
>>     the
>>       function signature.
>>
>> I agree, but Travis likes this section and I don't feel strongly
>>       about it.
> 
> If I understood its role properly, I would be happier to use it, but
> at the moment I'm not convinced that it contributes anything useful.
> Parameters are normally sorted from most to least valuable anyway.

Look at the scipy.optimize.fmin*() functions, for instance. If you don't feel 
like using it, don't. None of the numpy function signatures should be long 
enough to need it.

>>     5. Is the {'hi', 'ho'} syntax used when a parameter can only assume a
>>       limited number of values?  In Python {} is a dictionary, so why not
>>       use ('hi','ho') instead?
>>
>> Either would be fine. IIRC, the {} was inherited from epydoc consolidated
>> fields.
> 
> I thought that, since we threw all epydoc guidelines out the window,
> this would be a good time talk about it -- the next docday is just
> around the corner!

Personally, I don't think it's worth standardizing. If it's readable and valid 
reST, just do it.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
  that is made terrible by our own mad attempt to interpret it as though it had
  an underlying truth."
   -- Umberto Eco


More information about the Numpy-discussion mailing list