gmane.comp.python.scientific.devel

Neil Crighton | 16 Aug 16:36

Guidelines for documenting parameter types

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

I don't mind what we end up deciding on, but I think it's a good idea
to address these situations in the guidelines so new people know what
to do, and can feel comfortable about cleaning up someone else's
docstring to match the guidelines (if necessary). Maybe some of these
are pedantic, but I think they'll help to give the docs a more unified
feel and make sure it's always clear what parameter types are meant.

(1) When we mention types in the parameters, we are mostly using the
following abbreviations:

integer : int
float : float
boolean : bool
complex : complex
list : list
tuple : tuple

i.e. the same as the python function names for each type.  It would be
nice to say in the guidelines that these should be followed where
possible.

(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

(Continue reading)

headers

| 17 Aug 05:49

Re: Guidelines for documenting parameter types

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

(Continue reading)

headers

Bruce Southey | 18 Aug 16:56

Re: Guidelines for documenting parameter types

Neil Crighton wrote:
> (1) When we mention types in the parameters, we are mostly using the
> following abbreviations:
>
> integer : int
> float : float
> boolean : bool
> complex : complex
> list : list
> tuple : tuple
>
> i.e. the same as the python function names for each type.  It would be
> nice to say in the guidelines that these should be followed where
> possible.
>   
I agree with the addition of the default precision because NumPy 
supports multiple numerical precisions. At least the output text or 
notes section must indicate when NumPy changes the numerical precision:
 >>> a=np.array([1,2,3], dtype=np.int8)
 >>> type(np.mean(a))
<type 'numpy.float64'>
 >>> a=np.array([1,2,3], dtype=np.float32)
 >>> type(np.mean(a))
<type 'numpy.float64'>
 >>> a=np.array([1,2,3], dtype=np.float128)
 >>> type(np.mean(a))
<type 'numpy.float128'>

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

(Continue reading)