[Numpy-discussion] Proposed enhancement to "Returns" section for numpy doc strings

[Rob Ruana]

I am an admirer of the numpy doc string style. I'd like to propose a simple
enhancement to the Returns section that should make the common case more
readable, while maintaining backward compatibility with existing
documentation.

The current numpy documentation spec [1] requires that return values are
named. Most of the time I only care about the return *type* of a function,
and I can't be bothered to come up with a name. Of course, I can use the
default "out" return name, but that adds nothing of value to the
documentation, and takes away from the readability. I'd really like to just
write:

    Returns
    -------
    bool
        True if some condition, False otherwise.

Of course there are times when names can *enhance* the documentation, for
example numpy.meshgrid:

    Returns
    -------
    X1, X2,..., XN : ndarray
        For vectors `x1`, `x2`,..., 'xn' with lengths ``Ni=len(xi)`` ,
        return ``(N1, N2, N3,...Nn)`` shaped arrays if indexing='ij'
        or ``(N2, N1, N3,...Nn)`` shaped arrays if indexing='xy'
        with the elements of `xi` repeated to fill the matrix along
        the first dimension for `x1`, the second for `x2` and so on.

I suggest that the *name* of each return value should be optional, while
the *type* is required. This would allow for the common case, while still
supporting the documentation as it stands.

I've implemented this change in the numpydoc_returns_unnamed feature branch
on my github fork. The numpydoc sphinx extension has been updated, as well
as the reStructuredText example.py and the guide to numpy documentation.

Please review my pull request (https://github.com/numpy/numpy/pull/3468)
and let me know what you think.


[1]:
https://github.com/numpy/numpy/blob/7af95b0f779f587dfe56c44c5091731b122ceb1a/doc/HOWTO_DOCUMENT.rst.txt
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20130625/eba01970/attachment.html>