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

[Stefan van der Walt]

Hi all,

The numpy documentation standard example shows:

    Parameters
    ----------
    var1 : array_like
        Array_like means all those objects -- lists, nested lists, etc. --
        that can be converted to an array.
    var2 : integer
        Write out the full type
    long_variable_name : {'hi', 'ho'}, optional
        Choices in brackets, default first when optional.

I'd like to know:

1. "array_like" describes objects that can be forced to quack like
   ndarrays.  Are there any other such "special" descriptions?

2. How do we specify default values?

3. Why do we need the "optional" keyword (the function signature
   already indicates that the parameter is optional).

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.

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?

Thanks for your feedback!

Regards
Stéfan