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
_______________________________________________
Numpy-discussion mailing list
Numpy-discussion@scipy.org
http://projects.scipy.org/mailman/listinfo/numpy-discussion
