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