[Numpy-discussion] Help!!! Docstrings overrun by markup crap.

[Charles R Harris]

Example,

    Compute the qr factorization of a matrix.
>
>     Factor the matrix `a` as `qr`, where `q` is orthonormal
>     (:math:`dot( q_{:,i}, q_{:,j}) = \delta_{ij}`, the Kronecker delta) and
>     `r` is upper-triangular.
>

Arrggghhhh... Totally. Unreadable. Why not say the columns of q are
orthonormal vectors and r is upper triangular? The math tutorial should go
in the notes, if anywhere. Might mention that this is a 'thin' factorization
(Golub). Let me propose a rule: no math markup in the summary, ever.

    Parameters
>     ----------
>     a : array_like, shape (M, N)
>         Matrix to be factored.
>     mode : {'full', 'r', 'economic'}
>         Specifies the information to be returned. 'full' is the default.
>         mode='r' returns a "true" `r`, while 'economic' returns a
> "polluted"
>         `r` (albeit slightly faster; see Returns below).
>
>

Oh, come now, "true", "polluted"? Sounds a bit political... Actually,
'economic' contains info on the Householder reflections. In any case, why
mention it at all, just refer to the return documentation. And wouldn't
values be a better word than information?


>     Returns
>     -------
>     * If mode = 'full':
>
>         * q : ndarray of float or complex, shape (M, K)
>         * r : ndarray of float or complex, shape (K, N)
>
>       Size K = min(M, N)
>
>     * If mode = 'r':
>
>       * r : ndarray of float or complex, shape (K, N)
>
>     * If mode = 'economic':
>
>       * a2 : ndarray of float or complex, shape (M, N)
>
>       The diagonal and the upper triangle of a2 contains r,
>       while the rest of the matrix is undefined.
>

WTF? I'm seeing stars.

I may be old and crotchety, and I don't mean to be mean to the folks who
have done the hard work to bring the docstring to its current state, but I
think things have gotten out of hand.

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