Docstring for rank_order

TODO: write a graphical example using rank_order (reassigning labels
in segmented objects, for example)

scikits/image/filter/rank_order.py

@@ -13,8 +13,36 @@ import numpy
 def rank_order(image):
     """Return an image of the same shape where each pixel has the
     rank-order value of the corresponding pixel in the image.
-    The returned image's elements are of type numpy.uint32 which
-    simplifies processing in C code.
+
+    Parameters
+    ----------
+    image: ndarray
+
+    Returns
+    -------
+    labels: ndarray of type np.uint32, of shape image.shape
+        New array where each pixel has the rank-order value of the
+        corresponding pixel in `image`. Pixel values are between 0 and
+        n - 1, where n is the number of distinct unique values in
+        `image`.
+
+    original_values: 1-d ndarray
+        Unique original values of `image`
+
+    Examples
+    --------
+    >>> a = np.array([[1, 4, 5], [4, 4, 1], [5, 1, 1]])
+    >>> a
+    array([[1, 4, 5],
+        [4, 4, 1],
+        [5, 1, 1]])
+    >>> rank_order(a)
+    (array([[0, 1, 2],
+        [1, 1, 0],
+        [2, 0, 0]], dtype=uint32), array([1, 4, 5]))
+    >>> b = np.array([-1., 2.5, 3.1, 2.5])
+    >>> rank_order(b)
+    (array([0, 1, 2, 1], dtype=uint32), array([-1. ,  2.5,  3.1]))
     """
     flat_image = image.ravel()
     sort_order = flat_image.argsort().astype(numpy.uint32)