[SciPy-dev] Guidelines for documenting parameter types

[Stéfan van der Walt]

Hi Neil

2008/8/16 Neil Crighton <neilcrighton at gmail.com>:
> A few of us participating in the doc marathon
> (http://sd-2116.dedibox.fr/pydocweb/wiki/Front%20Page/) have some
> questions about documenting parameter types, and I thought it would be
> good to get others' opinions.  If we can agree on some guidelines,
> perhaps they could be incorporated into the docstring standard
> (http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines#docstring-standard)?

Thank you for bringing this conversation to the table.  I'm replying
only to scipy-dev, since I don't want to flood both mailing lists.

> (2) Often it's useful to state the type of an input or returned array.
> If we want to say the array returned by np.all is of type bool, what
> should we say? Possibilities used so far are
>
> int array
> array of int
> array of ints
>
> I prefer 'array of ints', because it is also suitable for tuples and
> lists ('tuple of ints', or 'list of dtypes'). 'int tuple' is just bad
> :) .

I like 'array of ints' too.  Unless there are objections, let's stick to that.

> (4) Sometimes we need to specify more than one kind of type.  For
> example, the shape parameter of zeros can be either an int or a
> sequence of ints (but is not array_like, since it doesn't accepted
> nested sequences). How should we write this? Some possibilities are:
>
> int or sequence of ints
> {int, sequence of ints}

I like the first option, 'int or sequence of ints'.

> (5) For keyword arguments, the default value is often None. In this
> case we've been omitting None from the parameter types. However,
> sometimes None is a valid input type but is not the default (e.g. axis
> keyword for argsort). In this case I think it's a good idea to include
> None as an explicit parameter.

Good point.

Thank you for considering all of these cases.  I'll wait a few days
for more comments on the thread, but I like your suggestions above and
will incorporate them into the standard unless anyone objects.

Cheers
Stéfan