doc: in pcolormesh docstring, say what it does.

efiring · efiring · commit 52c0b1d0c63e · 2012-08-13T09:05:01.000-10:00
diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py
@@ -7221,6 +7221,16 @@ def pcolormesh(self, *args, **kwargs):
           pcolormesh(X, Y, C)
           pcolormesh(C, **kwargs)
 
+        Create a pseudocolor plot of a 2-D array.
+
+        pcolormesh is similar to :func:`~matplotlib.pyplot.pcolor`,
+        but uses a different mechanism and returns a different
+        object; pcolor returns a
+        :class:`~matplotlib.collections.PolyCollection` but pcolormesh
+        returns a
+        :class:`~matplotlib.collections.QuadMesh`.  It is much faster,
+        so it is almost always preferred for large arrays.
+
         *C* may be a masked array, but *X* and *Y* may not.  Masked
         array support is implemented via *cmap* and *norm*; in
         contrast, :func:`~matplotlib.pyplot.pcolor` simply does not
