Clarify and fix docstrings

skimage/morphology/binary.py

@@ -7,7 +7,7 @@ from .misc import default_selem
 
 
 # The default_selem decorator provides a diamond structuring element as default
-# with the appropriate dimension for the input `image`.
+# with the same dimension as the input image and size 3 along each axis.
 @default_selem
 def binary_erosion(image, selem=None, out=None):
     """Return fast binary morphological erosion of an image.

skimage/morphology/grey.py

@@ -15,8 +15,8 @@ __all__ = ['erosion', 'dilation', 'opening', 'closing', 'white_tophat',
 def _shift_selem(selem, shift_x, shift_y):
     """Shift the binary image `selem` in the left and/or up.
 
-    This only affects structuring elements with even number of rows or
-    columns.
+    This only affects 2D structuring elements with even number of rows
+    or columns.
 
     Parameters
     ----------
@@ -63,7 +63,7 @@ def _invert_selem(selem):
 
     Returns
     -------
-    inverted : array
+    inverted : array, same shape and type as `selem`
         The structuring element, in opposite order.
 
     Examples
@@ -89,13 +89,14 @@ def pad_for_eccentric_selems(func):
     ----------
     func : callable
         A morphological function, either opening or closing, that
-        supports eccentric structuring elements. The inputs must
+        supports eccentric structuring elements. Its parameters must
         include at least `image`, `selem`, and `out`.
 
     Returns
     -------
     func_out : callable
-        A function
+        The same function, but correctly padding the input image before
+        applying the input function.
 
     See Also
     --------
@@ -156,9 +157,9 @@ def erosion(image, selem=None, out=None, shift_x=False, shift_y=False):
 
     Notes
     -----
-    For `uint8` (and `uint16` up to a certain bit-depth) data, the lower
-    algorithm complexity makes the `skimage.filter.rank.minimum` function more
-    efficient for larger images and structuring elements.
+    For ``uint8`` (and ``uint16`` up to a certain bit-depth) data, the
+    lower algorithm complexity makes the `skimage.filter.rank.minimum`
+    function more efficient for larger images and structuring elements.
 
     Examples
     --------
@@ -211,7 +212,7 @@ def dilation(image, selem=None, out=None, shift_x=False, shift_y=False):
 
     Returns
     -------
-    dilated : uint8 array
+    dilated : uint8 array, same shape and type as `image`
         The result of the morphological dilation.
 
     Notes
@@ -273,7 +274,7 @@ def opening(image, selem=None, out=None):
 
     Returns
     -------
-    opening : array
+    opening : array, same shape and type as `image`
         The result of the morphological opening.
 
     Examples
@@ -323,7 +324,7 @@ def closing(image, selem=None, out=None):
 
     Returns
     -------
-    closing : array
+    closing : array, same shape and type as `image`
         The result of the morphological closing.
 
     Examples
@@ -371,7 +372,7 @@ def white_tophat(image, selem=None, out=None):
 
     Returns
     -------
-    out : array
+    out : array, same shape and type as `image`
         The result of the morphological white top hat.
 
     Examples
@@ -425,7 +426,7 @@ def black_tophat(image, selem=None, out=None):
 
     Returns
     -------
-    opening : uint8 array
+    opening : array, same shape and type as `image`
        The result of the black top filter.
 
     Examples

skimage/segmentation/boundaries.py

@@ -203,6 +203,10 @@ def mark_boundaries(image, label_img, color=(1, 1, 0),
     if marked.ndim == 2:
         marked = gray2rgb(marked)
     if mode == 'subpixel':
+        # Here, we want to interpose an extra line of pixels between
+        # each original line — except for the last axis which holds
+        # the RGB information. ``nd.zoom`` then performs the (cubic)
+        # interpolation, filling in the values of the interposed pixels
         marked = nd.zoom(marked, [2 - 1/s for s in marked.shape[:-1]] + [1],
                          mode='reflect')
     boundaries = find_boundaries(label_img, mode=mode,

skimage/util/arraypad.py

@@ -1507,25 +1507,25 @@ def crop(ar, crop_width, copy=False, order='K'):
         Input array.
     crop_width : {sequence, int}
         Number of values to remove from the edges of each axis.
-        ((before_1, after_1), ... (before_N, after_N)) specifies unique
-        crop widths at the start and end of each axis.
-        ((before, after),) specifies the same start and end crops for
-        every axis.
-        (int,) or int is a shortcut for before = after = int for all
-        axes.
+        ``((before_1, after_1),`` ... ``(before_N, after_N))`` specifies
+        unique crop widths at the start and end of each axis.
+        ``((before, after),)`` specifies a fixed start and end crop
+        for every axis.
+        ``(n,)`` or ``n`` for integer ``n`` is a shortcut for
+        before = after = ``n`` for all axes.
     copy : bool, optional
-        Ensure that the returned array is contiguous. Normally, a crop
+        Ensure the returned array is a contiguous copy. Normally, a crop
         operation will return a discontiguous view of the underlying
-        input array. Passing `copy=True` will result in a contiguous
+        input array. Passing ``copy=True`` will result in a contiguous
         copy.
     order : {'C', 'F', 'A', 'K'}, optional
-        If `copy==True`, control the memory layout of the copy. See
-        `np.copy`.
+        If ``copy==True``, control the memory layout of the copy. See
+        ``np.copy``.
 
     Returns
     -------
     cropped : array
-        The cropped array. If `copy=False` (default), this is a sliced
+        The cropped array. If ``copy=False`` (default), this is a sliced
         view of the input array.
     """
     ar = np.array(ar, copy=False)