[SciPy-Dev] docstring standard: parameter shape description

[Ralf Gommers]

Hi,

When merging the doc wiki edits there were a large number of changes to the
shape description of parameters/returns. This is not yet described in the
docstring standard (
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt), and
currently is done in various ways:

param1 : ndarray, shape (N,)

param1 : ndarray of shape (N,)

param1 : (N,) ndarray

param1 : 1-D ndarray

param1 : ndarray
    A 1-D array ....

To keep this consistent I'd like to add it to the standard. My proposal
would be:
1. If the actual shape is used in the description (for example to say
"return size is N+1), then use:
    param1 : ndarray, shape (N,)
2. If it's not used but has to be 1-D (or 2-D, ...), then use:
    param1 : 1-D ndarray

This post was triggered by doc wiki edits and a review comment on those at
https://github.com/scipy/scipy/pull/405 by the way.

Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20130127/85d2cfa0/attachment.html