matplotlib
diff --git a/‎lib/matplotlib/colorbar.py
Lines changed: 18 additions & 21 deletions b/‎lib/matplotlib/colorbar.py
Lines changed: 18 additions & 21 deletions
@@ -141,12 +141,12 @@
 Parameters
 ----------
 mappable
-    The :class:`~matplotlib.image.Image`,
-    :class:`~matplotlib.contour.ContourSet`, etc. to
-    which the colorbar applies; this argument is mandatory for the Figure
-    :meth:`~matplotlib.figure.Figure.colorbar` method but optional for the
-    pyplot :func:`~matplotlib.pyplot.colorbar` function, which sets the
-    default to the current image.
+    The `~matplotlib.cm.ScalarMappable` (i.e., `~matplotlib.image.Image`,
+    `~matplotlib.contour.ContourSet`, etc.) to which the colorbar
+    applies.  This argument is mandatory for the Figure method
+    `~matplotlib.figure.Figure.colorbar` but optional for the pyplot function
+    `~matplotlib.pyplot.colorbar` function, which sets the default to the
+    current image.
 
 cax : :class:`~matplotlib.axes.Axes` object, optional
     Axes into which the colorbar will be drawn.
@@ -157,18 +157,15 @@
     colorbar axes.
 
 use_gridspec : bool, optional
-    If *cax* is ``None``, a new *cax* is created as an instance of
-    Axes. If *ax* is an instance of Subplot and *use_gridspec* is ``True``,
-    *cax* is created as an instance of Subplot using the
-    grid_spec module.
-
+    If *cax* is ``None``, a new *cax* is created as an instance of Axes.  If
+    *ax* is an instance of Subplot and *use_gridspec* is ``True``, *cax* is
+    created as an instance of Subplot using the :mod:`~.gridspec` module.
 
 Returns
 -------
 :class:`~matplotlib.colorbar.Colorbar` instance
-    See also its base class, :class:`~matplotlib.colorbar.ColorbarBase`.
-    Call the :meth:`~matplotlib.colorbar.ColorbarBase.set_label` method
-    to label the colorbar.
+    See also its base class, `~matplotlib.colorbar.ColorbarBase`.  Call the
+    `~.set_label` method to label the colorbar.
 
 Notes
 -----
@@ -183,25 +180,25 @@
 kwarg is included automatically.
 
 The *shrink* kwarg provides a simple way to scale the colorbar with respect
-to the axes. Note that if *cax* is specified it determines the size of the
+to the axes. Note that if *cax* is specified, it determines the size of the
 colorbar and *shrink* and *aspect* kwargs are ignored.
 
 For more precise control, you can manually specify the positions of
 the axes objects in which the mappable and the colorbar are drawn.  In
 this case, do not use any of the axes properties kwargs.
 
-It is known that some vector graphics viewer (svg and pdf) renders white gaps
-between segments of the colorbar. This is due to bugs in the viewers not
-matplotlib. As a workaround the colorbar can be rendered with overlapping
+It is known that some vector graphics viewers (svg and pdf) renders white gaps
+between segments of the colorbar.  This is due to bugs in the viewers, not
+Matplotlib.  As a workaround, the colorbar can be rendered with overlapping
 segments::
 
     cbar = colorbar()
     cbar.solids.set_edgecolor("face")
     draw()
 
-However this has negative consequences in other circumstances. Particularly
-with semi transparent images (alpha < 1) and colorbar extensions and is not
-enabled by default see (issue #1188).
+However this has negative consequences in other circumstances, e.g. with
+semi-transparent images (alpha < 1) and colorbar extensions; therefore, this
+workaround is not used by default (see issue #1188).
 
 ''' % (make_axes_kw_doc, colormap_kw_doc)