[SciPy-user] Docstring standards for NumPy and SciPy

[Fernando Perez]

On 1/17/07, Travis Oliphant <oliphant.travis at ieee.org> wrote:

> > No, please let's explicitly differentiate between keywords and
> > positional arguments.  I don't care much what they are called, but
> > there's a sharp functional difference in the language between the two:
> > you can NOT omit positional arguments while you can omit keywords (or
> > call them arguments-with-defaults, or whatever).
>
> But, whether or not one has a positional or keyword argument is obvious
> from the calling information, right?

... which is inaccessible if the function is written in C, for example:

In [2]: n.cos?
Type:           ufunc
Base Class:     <type 'numpy.ufunc'>
Namespace:      Interactive
Docstring:
    y = cos(x) cosine elementwise.

The call line can only be introspected out (which is what ipython,
help() and other tools do) if the function is written in pure python.

Also, a formatting system may not properly show an extra blank line in
the middle of a formatted list.  reST for example makes blank lines
/optional/ between lists, so it would collapse all arguments in your
convention (I think) into a single list.

IMHO, relying on something as brittle as a single line of whitespace
(which may well be swallowed by the renderer du jour) for conveying
this distinction is not a good idea.

And having different conventions for different cases (such as
f(*a,**k) or C functions) is also, I think, not very nice.  I'd rather
this be consistent across /all/ cases.

Just my 1e-2, ultimately I'm just happy to see /something/ emerge.

f