[SciPy-Dev] docstring standard: parameter shape description

[Ralf Gommers]

On Tue, Jan 29, 2013 at 5:27 AM, Cera, Tim <tim@cerazone.net> wrote:

> As I was typing out the examples above I realized the `param3` proves my
>> point.  If ``K`` is not mentioned then Ralf's initial suggested docstring
>> standard would have described the shape of `param3` in the text.  This
>> would make the  'param3 : ...' line and 'param1 : ...' line seem to
>> indicate the same thing.  You would have to read the text to see the
>> difference.  Now, how often does this happen where you have parameters of
>> different shapes that would confuse under the proposed standard?  I have no
>> idea.
>>
>
> I want to take back this last paragraph.  Looked again at Ralf's
> suggestion and there would be a difference.  The examples from the previous
> message would be...
>
>  param1 : array_like
>     Can be any shape...
> param2 : array_like, shape(N,)
>     A 1D array, specified because ``N`` is used.
> param3 : 1D array_like
>     Another 1D array
>
> I tried to find a grammar site to determine what the standard was for
> dimensionality, but didn't find anything.  Is it 1-D, 1D, or 1-d?  Seems
> that most people are going with 1D though, but that determination should
> also be part of the standard if we accept Ralf's initial proposal.
>

I'm pretty sure we decided on 1-D, but it's not written down either.

Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20130129/5c14df5a/attachment.html