Merge pull request #3628 from switham/master

tacaswell · tacaswell · commit 7f71233d5568 · 2014-10-16T19:28:19.000-04:00
DOC : Document auto-init behavior of colors.Normalize and cm.ScalarMappable.
diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
@@ -178,9 +178,10 @@ def __init__(self, norm=None, cmap=None):
         norm : :class:`matplotlib.colors.Normalize` instance
             The normalizing object which scales data, typically into the
             interval ``[0, 1]``.
+            If *None*, *norm* defaults to a *colors.Normalize* object which
+            initializes its scaling based on the first data processed.
         cmap : str or :class:`~matplotlib.colors.Colormap` instance
             The colormap used to map normalized data values to RGBA colors.
-
         """
 
         self.callbacksSM = cbook.CallbackRegistry()
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -851,10 +851,12 @@ class Normalize(object):
     """
     def __init__(self, vmin=None, vmax=None, clip=False):
         """
-        If *vmin* or *vmax* is not given, they are taken from the input's
-        minimum and maximum value respectively.  If *clip* is *True* and
-        the given value falls outside the range, the returned value
-        will be 0 or 1, whichever is closer. Returns 0 if::
+        If *vmin* or *vmax* is not given, they are initialized from the
+        minimum and maximum value respectively of the first input
+        processed.  That is, *__call__(A)* calls *autoscale_None(A)*.
+        If *clip* is *True* and the given value falls outside the range,
+        the returned value will be 0 or 1, whichever is closer.
+        Returns 0 if::
 
             vmin==vmax
 
@@ -902,6 +904,13 @@ def process_value(value):
         return result, is_scalar
 
     def __call__(self, value, clip=None):
+        """
+        Normalize *value* data in the ``[vmin, vmax]`` interval into
+        the ``[0.0, 1.0]`` interval and return it.  *clip* defaults
+        to *self.clip* (which defaults to *False*).  If not already
+        initialized, *vmin* and *vmax* are initialized using
+        *autoscale_None(value)*.
+        """
         if clip is None:
             clip = self.clip
 
