Merge pull request matplotlib#10831 from timhoffm/doc-binned

Minor docstring updates on binning related plot functions

Author: anntzer

lib/matplotlib/axes/_axes.py

@@ -4193,11 +4193,10 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
         of the observations at (x[i],y[i]).
 
         If *C* is specified, it specifies values at the coordinate
-        (x[i],y[i]). These values are accumulated for each hexagonal
+        (x[i], y[i]). These values are accumulated for each hexagonal
         bin and then reduced according to *reduce_C_function*, which
-        defaults to numpy's mean function (np.mean). (If *C* is
-        specified, it must also be a 1-D sequence of the same length
-        as *x* and *y*.)
+        defaults to `numpy.mean`. (If *C* is specified, it must also
+        be a 1-D sequence of the same length as *x* and *y*.)
 
         Parameters
         ----------
@@ -4213,7 +4212,7 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
             tuple with two elements specifying the number of hexagons
             in the *x*-direction and the *y*-direction.
 
-        bins : {'log'} or int or sequence, optional, default is *None*
+        bins : 'log' or int or sequence, optional, default is *None*
             If *None*, no binning is applied; the color of each hexagon
             directly corresponds to its count value.
 
@@ -4289,11 +4288,9 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
 
         Returns
         -------
-        object
-            a :class:`~matplotlib.collections.PolyCollection` instance; use
-            :meth:`~matplotlib.collections.PolyCollection.get_array` on
-            this :class:`~matplotlib.collections.PolyCollection` to get
-            the counts in each hexagon.
+        polycollection
+            A `.PolyCollection` instance; use `.PolyCollection.get_array` on
+            this to get the counts in each hexagon.
 
             If *marginals* is *True*, horizontal
             bar and vertical bar (both PolyCollections) will be attached
@@ -6060,11 +6057,11 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
         ----------
         x : (n,) array or sequence of (n,) arrays
             Input values, this takes either a single array or a sequence of
-            arrays which are not required to be of the same length
+            arrays which are not required to be of the same length.
 
-        bins : integer or sequence or 'auto', optional
+        bins : int or sequence or str, optional
             If an integer is given, ``bins + 1`` bin edges are calculated and
-            returned, consistent with :func:`numpy.histogram`.
+            returned, consistent with `numpy.histogram`.
 
             If `bins` is a sequence, gives bin edges, including left edge of
             first bin and right edge of last bin.  In this case, `bins` is
@@ -6081,9 +6078,12 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
 
             Unequally spaced bins are supported if *bins* is a sequence.
 
-            If Numpy 1.11 is installed, may also be ``'auto'``.
+            With Numpy 1.11 or newer, you can alternatively provide a string
+            describing a binning strategy, such as 'auto', 'sturges', 'fd',
+            'doane', 'scott', 'rice', 'sturges' or 'sqrt', see
+            `numpy.histogram`.
 
-            Default is taken from the rcParam ``hist.bins``.
+            The default is taken from :rc:`hist.bins`.
 
         range : tuple or None, optional
             The lower and upper range of the bins. Lower and upper outliers
@@ -6096,7 +6096,7 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
 
             Default is ``None``
 
-        density : boolean, optional
+        density : bool, optional
             If ``True``, the first element of the return tuple will
             be the counts normalized to form a probability density, i.e.,
             the area (or integral) under the histogram will sum to 1.
@@ -6120,7 +6120,7 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
 
             Default is ``None``
 
-        cumulative : boolean, optional
+        cumulative : bool, optional
             If ``True``, then a histogram is computed where each bin gives the
             counts in that bin plus all bins for smaller values. The last bin
             gives the total number of datapoints. If *normed* or *density*
@@ -6180,7 +6180,7 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
 
             Default is ``None``
 
-        log : boolean, optional
+        log : bool, optional
             If ``True``, the histogram axis will be set to a log scale. If
             *log* is ``True`` and *x* is a 1D array, empty bins will be
             filtered out and only the non-empty ``(n, bins, patches)``
@@ -6194,14 +6194,14 @@ def hist(self, x, bins=None, range=None, density=None, weights=None,
 
             Default is ``None``
 
-        label : string or None, optional
+        label : str or None, optional
             String, or sequence of strings to match multiple datasets.  Bar
             charts yield multiple patches per dataset, but only the first gets
             the label, so that the legend command will work as expected.
 
             default is ``None``
 
-        stacked : boolean, optional
+        stacked : bool, optional
             If ``True``, multiple data are stacked on top of each other If
             ``False`` multiple data are arranged side by side if histtype is
             'bar' or on top of each other if histtype is 'step'
@@ -6555,10 +6555,10 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
 
         Parameters
         ----------
-        x, y: array_like, shape (n, )
+        x, y : array_like, shape (n, )
             Input values
 
-        bins: [None | int | [int, int] | array_like | [array, array]]
+        bins : None or int or [int, int] or array_like or [array, array]
 
             The bin specification:
 
@@ -6582,7 +6582,7 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
              xmax], [ymin, ymax]]. All values outside of this range will be
              considered outliers and not tallied in the histogram.
 
-        normed : boolean, optional, default: False
+        normed : bool, optional, default: False
              Normalize histogram.
 
         weights : array_like, shape (n, ), optional, default: None
@@ -6612,7 +6612,7 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
 
         Other Parameters
         ----------------
-        cmap : {Colormap, string}, optional
+        cmap : Colormap or str, optional
             A :class:`matplotlib.colors.Colormap` instance.  If not set, use rc
             settings.
 
@@ -6621,7 +6621,7 @@ def hist2d(self, x, y, bins=10, range=None, normed=False, weights=None,
             scale luminance data to ``[0, 1]``. If not set, defaults to
             ``Normalize()``.
 
-        vmin/vmax : {None, scalar}, optional
+        vmin/vmax : None or scalar, optional
             Arguments passed to the `Normalize` instance.
 
         alpha : ``0 <= scalar <= 1`` or ``None``, optional