cf. discussion in #6366.

These fixes are not agressive as some of the code is complicated
and it is better to be careful.

The files numeric.py and numerictypes.py are not easily analysed
and the latter is self modifying. Pyflakes generates a number of
invalid warnings for those files.

Most of these fixes involve putting blank lines around

.. versionadded:: x.x.x

and

.. deprecated:: x.x.x

Some of the examples were also fixed.

DOC: Update indexing docs. 

Update docs for boolean array indexing and nonzero order.
Add links to row-major and column-major terms where they appear.

Closes #3177

Risky perhaps. The old correlate behavior was deprecated in NumPy 1.4
and the default behavior changed to the new (standard) version in 1.5.
The old function, with slightly different signature, is still available
in numpy.core.multiarray.correlate.

If this causes problems in the 1.10 release process, this commit can be
reverted.

Some keywords are deprecated and slated for removal in numpy 2.0.
Add comment to deprecation date to clarify that.

This is to make it easier to find and remove deprecated features.
It would be a good idea if all deprecations were made with similar
comments.

This is the functional counterpart of the '@' operator that will be
available in Python 3.5 with the addition of an out keyword. It
operates like the dot function except that

- scalar multiplication is not allowed.
- multiplication of arrays with more than 2 dimensions broadcasts.

The last means that when arrays have more than 2 dimensions they are
treated as stacks of matrices and those stacks are broadcast against
each other unlike the current behavior of dot that does an outer
product. Like dot, matmul is aware of `__numpy_ufunc__` and can be
overridden.

The current version of the function uses einsum when cblas cannot be
used, hence object arrays are not yet supported.