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

[Stefan van der Walt]

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.

>     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.

>     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!

Thank you very much for your response.

Regards
Stéfan