[SciPy-Dev] docstring standard: parameter shape description

[Cera, Tim]

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

Kindest regards,
Tim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20130128/2a89386d/attachment.html>