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
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion