Review comments

apaszke · apaszke · commit 6af6818471c4 · 2020-03-12T12:00:39.000+01:00
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -2003,18 +2003,46 @@ def _array_perimeter(arr):
 
 
 def _unfold(arr, axis, size, step):
-    """Append an extra dimension containing sliding windows along **axis**.
+    """
+    Append an extra dimension containing sliding windows along *axis*.
 
-    All windows are of size **size** and begin with every **step** elements.
+    All windows are of size *size* and begin with every *step* elements.
 
     Parameters
     ----------
     arr : ndarray, shape (N_1, ..., N_k)
         The input array
+    axis : int
+        Axis along which the windows are extracted
+    size : int
+        Size of the windows
+    step : int
+        Stride between first elements of subsequent windows.
 
     Returns
     -------
     windows : ndarray, shape (N_1, ..., 1 + (N_axis-size)/step, ..., N_k, size)
+
+    Examples
+    --------
+    >>> i, j = np.ogrid[:3,:7]
+    >>> a = i*10 + j
+    >>> a
+    array([[ 0,  1,  2,  3,  4,  5,  6],
+        [10, 11, 12, 13, 14, 15, 16],
+        [20, 21, 22, 23, 24, 25, 26]])
+    >>> _unfold(a, axis=1, size=3, step=2)
+    array([[[ 0,  1,  2],
+            [ 2,  3,  4],
+            [ 4,  5,  6]],
+
+           [[10, 11, 12],
+            [12, 13, 14],
+            [14, 15, 16]],
+
+           [[20, 21, 22],
+            [22, 23, 24],
+            [24, 25, 26]]])
     """
     new_shape = [*arr.shape, size]
     new_strides = [*arr.strides, arr.strides[axis]]
@@ -2027,19 +2055,25 @@ def _unfold(arr, axis, size, step):
 
 
 def _array_patch_perimeters(x, rstride, cstride):
-    """Extract perimeters of patches from **arr**.
+    """
+    Extract perimeters of patches from *arr*.
 
-    Extracted patches are of size (**rstride** + 1) x (**cstride** + 1) and
+    Extracted patches are of size (*rstride* + 1) x (*cstride* + 1) and
     share perimeters with their neighbors. The ordering of the vertices matches
     that returned by ``_array_perimeter``.
 
     Parameters
     ----------
-    arr : ndarray, shape (N, M)
+    x : ndarray, shape (N, M)
+        Input array
+    rstride : int
+        Vertical (row) stride between corresponding elements of each patch
+    cstride : int
+        Horizontal (column) stride between corresponding elements of each patch
 
     Returns
     -------
-    patches : ndarray, shape (N / rstride * M / cstride, 2(rstride + cstride))
+    patches : ndarray, shape (N/rstride * M/cstride, 2 * (rstride + cstride))
     """
     assert rstride > 0 and cstride > 0
     assert (x.shape[0] - 1) % rstride == 0
diff --git a/lib/matplotlib/tests/test_cbook.py b/lib/matplotlib/tests/test_cbook.py
@@ -594,6 +594,8 @@ def test_warn_external(recwarn):
 
 
 def test_array_patch_perimeters():
+    # This compares the old implementation as a reference for the
+    # vectorized one.
     def check(x, rstride, cstride):
         rows, cols = x.shape
         row_inds = [*range(0, rows-1, rstride), rows-1]
