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

[Charles R Harris]

On Jan 23, 2008 6:55 AM, Stefan van der Walt <stefan at sun.ac.za> wrote:

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

I can't think of any, but that doesn't mean there aren't any.


> 2. How do we specify default values?
>

I like to put them first in the list: {-1, integer}


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


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


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

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20080123/83be3086/attachment.html>