[SciPy-Dev] docstring standard: parameter shape description

[josef.pktd at gmail.com]

On Sun, Jan 27, 2013 at 2:51 PM, Ralf Gommers <ralf.gommers at gmail.com> wrote:
> 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,)

I think the word "shape" is not really necessary.
Josef

>
> 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
>
>
>
>
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>