DOC/MNT : add docs + make helper function private

tacaswell · tacaswell · commit 5d4f5deac7f4 · 2017-04-03T15:18:01.000-04:00
diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py
@@ -62,16 +62,36 @@
 # how-to-encode-series-of-images-into-h264-using-x264-api-c-c )
 
 
-def correct_roundoff(x, dpi, n):
-    if int(x*dpi) % n != 0:
-        if int(np.nextafter(x, np.inf)*dpi) % n == 0:
-            x = np.nextafter(x, np.inf)
-        elif int(np.nextafter(x, -np.inf)*dpi) % n == 0:
-            x = np.nextafter(x, -np.inf)
-    return x
+def adjusted_figsize(w, h, dpi, n):
+    '''Compute figure size so that pixels are a multiple of n
 
+    Parameters
+    ----------
+    w, h : float
+        Size in inches
+
+    dpi : float
+        The dpi
+
+    n : int
+        The target multiple
+
+    Returns
+    -------
+    wnew, hnew : float
+        The new figure size in inches.
+    '''
+
+    # this maybe simplified if / when we adopt consistent rounding for
+    # pixel size across the whole library
+    def correct_roundoff(x, dpi, n):
+        if int(x*dpi) % n != 0:
+            if int(np.nextafter(x, np.inf)*dpi) % n == 0:
+                x = np.nextafter(x, np.inf)
+            elif int(np.nextafter(x, -np.inf)*dpi) % n == 0:
+                x = np.nextafter(x, -np.inf)
+        return x
 
-def adjusted_figsize(w, h, dpi, n):
     wnew = int(w * dpi / n) * n / dpi
     hnew = int(h * dpi / n) * n / dpi
     return (correct_roundoff(wnew, dpi, n), correct_roundoff(hnew, dpi, n))
@@ -350,6 +370,9 @@ def grab_frame(self, **savefig_kwargs):
         verbose.report('MovieWriter.grab_frame: Grabbing frame.',
                        level='debug')
         try:
+            # re-adjust the figure size in case it has been changed by the
+            # user.  We must ensure that every frame is the same size or
+            # the movie will not save correctly.
             self.fig.set_size_inches(self._w, self._h)
             # Tell the figure to save its data to the sink, using the
             # frame format and dpi.
