[Numpy-discussion] Docstring standard: how to specify variable types

[Charles R Harris]

On Jan 24, 2008 1:53 PM, Stefan van der Walt <stefan at sun.ac.za> wrote:

> Hi Robert
>
> On Thu, Jan 24, 2008 at 01:15:13PM -0600, Robert Kern wrote:
> > >>     5. Is the {'hi', 'ho'} syntax used when a parameter can only
> assume a
> > >>       limited number of values?  In Python {} is a dictionary, so why
> not
> > >>       use ('hi','ho') instead?
> > >>
> > >> Either would be fine. IIRC, the {} was inherited from epydoc
> consolidated
> > >> fields.
> > >
> > > I thought that, since we threw all epydoc guidelines out the window,
> > > this would be a good time talk about it -- the next docday is just
> > > around the corner!
> >
> > Personally, I don't think it's worth standardizing. If it's readable
> > and valid reST, just do it.
>
> The attached output shows the difference between using {} and () -- it
> doesn't seem to make a difference.  Since [] or () is normally used to
> indicate a set, I found it more natural.
>

I think it best for everyone to settle on one or the other, both for
consistency of appearance and later convenience if someone wants to parse
the documentation. Using neither {} nor () looks would also be reasonable,
but why don't we just go with the current standard? It was a bit of a
surprise to me, too. But *having* a working standard is more important than
the details. In the end, these things are just useful conventions. Sets are
normally defined using {} these days and set union and difference are no
longer '+' and '-'. There are old books where Euler angles are defined using
left handed coordinate systems. The Russian literature used '+' instead of
'-' as the sign in the exponential of the forward Fourier transform.
Strangest of all, in tensor analysis the meanings of covariant and
contravariant are interchanged. So all of those things could have gone
differently.

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20080124/d35cb535/attachment.html>