Document how to make colorbars "without" a ScalarMappable. (#13171)

anntzer · timhoffm · commit 5cbd04c35d43 · 2019-01-13T13:58:58.000+01:00
(Intentionally made the reference to ScalarMappable a fully qualified
one (removing the `~`), as it's probably a slightly obscure class...)
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
@@ -141,12 +141,17 @@
 Parameters
 ----------
 mappable
-    The `~matplotlib.cm.ScalarMappable` (i.e., `~matplotlib.image.Image`,
-    `~matplotlib.contour.ContourSet`, etc.) to which the colorbar applies.
+    The `matplotlib.cm.ScalarMappable` (i.e., `~matplotlib.image.Image`,
+    `~matplotlib.contour.ContourSet`, etc.) described by this colorbar.
     This argument is mandatory for the `.Figure.colorbar` method but optional
     for the `.pyplot.colorbar` function, which sets the default to the current
     image.
 
+    Note that one can create a `ScalarMappable` "on-the-fly" to generate
+    colorbars not attached to a previously drawn artist, e.g. ::
+
+        fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap, ax=ax))
+
 cax : :class:`~matplotlib.axes.Axes` object, optional
     Axes into which the colorbar will be drawn.
 
