Repository: numpy/numpy

Issue:
documentation of rollaxis
Hi,

On the web page https://docs.scipy.org/doc/numpy/reference/generated/numpy.rollaxis.html, where you document the rollaxis function, you first say:

Roll the specified axis backwards, until it lies in a given position.

then you write:

start : int, optional
The axis is rolled until it lies before this position. The default, 0, results in a “complete” roll.

There seems to be a contradiction between "lies in a given position" and "lies before this position", or at least the wording is confusing.   Also, it's not clear what a "complete" roll means.  I would think that a complete roll meant a 360-degree roll, which would be equivalent to no roll at all, but I don't think that's what you mean here.

As far as I can tell, "lies in a given position" is what the function really does.

Thanks,

Bruce Maggs

### Reproducing code example:

<!-- A short code example that reproduces the problem/missing feature. It should be
self-contained, i.e., possible to run as-is via 'python myproblem.py' -->

import numpy as np

>>> a = np.ones((3,4,5,6))
>>> np.rollaxis(a, 3, 1).shape
(3, 6, 4, 5)
>>> np.rollaxis(a, 2).shape
(5, 3, 4, 6)
>>> np.rollaxis(a, 1, 4).shape
(3, 5, 6, 4)






Discussion:
@BruceMaggs thanks for bringing this up ! The rolling backwards wording doesnt make much sense to me either.

```
>>> np.rollaxis(a, 1, 3).shape
(3, 5, 4, 6)
```

What I expected to happen
```
(3,4,5,6)
v
(4,3,5,6)
v
(6,3,5,4)
v
(6,3,4,5)
```


From the code, the provided axis seems to be removed from list of axis (axes) and inserted into the position start if start <= axis, and inserted into start - 1 pos if start > axis. The rolling backwards wording probably only applies if start <= axis. 

Maybe we should change the documentation to make it similar to moveaxis, to capture that we are "moving axis positions with source being the axis arg, and destination being start if start <= axis and start - 1 if start > axis. " One downside to this is that the rollaxis name may be confusing to users since this is very similar to moveaxis.

cc @charris 

Resolving patch:
diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -1226,11 +1226,39 @@ def rollaxis(a, axis, start=0):
     a : ndarray
         Input array.
     axis : int
-        The axis to roll backwards.  The positions of the other axes do not
+        The axis to be rolled. The positions of the other axes do not
         change relative to one another.
     start : int, optional
-        The axis is rolled until it lies before this position.  The default,
-        0, results in a "complete" roll.
+        When ``start <= axis``, the axis is rolled back until it lies in
+        this position. When ``start > axis``, the axis is rolled until it
+        lies before this position. The default, 0, results in a "complete"
+        roll. The following table describes how negative values of ``start``
+        are interpreted:
+
+        .. table::
+           :align: left
+
+           +-------------------+----------------------+
+           |     ``start``     | Normalized ``start`` |
+           +===================+======================+
+           | ``-(arr.ndim+1)`` | raise ``AxisError``  |
+           +-------------------+----------------------+
+           | ``-arr.ndim``     | 0                    |
+           +-------------------+----------------------+
+           | |vdots|           | |vdots|              |
+           +-------------------+----------------------+
+           | ``-1``            | ``arr.ndim-1``       |
+           +-------------------+----------------------+
+           | ``0``             | ``0``                |
+           +-------------------+----------------------+
+           | |vdots|           | |vdots|              |
+           +-------------------+----------------------+
+           | ``arr.ndim``      | ``arr.ndim``         |
+           +-------------------+----------------------+
+           | ``arr.ndim + 1``  | raise ``AxisError``  |
+           +-------------------+----------------------+
+           
+        .. |vdots|   unicode:: U+22EE .. Vertical Ellipsis
 
     Returns
     -------


Test patch: