DOC: Fix ordering of Other Parameters wrt Returns.

QuLogic · QuLogic · commit 65e767a87209 · 2020-03-20T17:24:37.000-04:00
The numpydoc sections listing is prescriptive, not descriptive, and the
order should be followed.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -377,14 +377,14 @@ def legend(self, *args, **kwargs):
             is shown in the legend and the automatic mechanism described above
             is not sufficient.
 
-        Other Parameters
-        ----------------
-        %(_legend_kw_doc)s
-
         Returns
         -------
         legend : `~matplotlib.legend.Legend`
 
+        Other Parameters
+        ----------------
+        %(_legend_kw_doc)s
+
         Notes
         -----
         Some artists are not supported by this function.  See
@@ -1572,6 +1572,11 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
                 You may suppress the warning by adding an empty format string
                 ``plot('n', 'o', '', data=obj)``.
 
+        Returns
+        -------
+        lines
+            A list of `.Line2D` objects representing the plotted data.
+
         Other Parameters
         ----------------
         scalex, scaley : bool, default: True
@@ -1593,11 +1598,6 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
 
             %(_Line2D_docstr)s
 
-        Returns
-        -------
-        lines
-            A list of `.Line2D` objects representing the plotted data.
-
         See Also
         --------
         scatter : XY scatter plot with markers of varying size and/or color (
@@ -2623,6 +2623,10 @@ def broken_barh(self, xranges, yrange, **kwargs):
         yrange : (*ymin*, *yheight*)
             The y-position and extend for all the rectangles.
 
+        Returns
+        -------
+        collection : `~.collections.BrokenBarHCollection`
+
         Other Parameters
         ----------------
         **kwargs : `.BrokenBarHCollection` properties
@@ -2641,10 +2645,6 @@ def broken_barh(self, xranges, yrange, **kwargs):
             Supported keywords:
 
             %(BrokenBarHCollection)s
-
-        Returns
-        -------
-        collection : `~.collections.BrokenBarHCollection`
         """
         # process the unit information
         if len(xranges):
@@ -3601,29 +3601,6 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
         zorder : scalar, default: None
             Sets the zorder of the boxplot.
 
-        Other Parameters
-        ----------------
-        showcaps : bool, default: True
-            Show the caps on the ends of whiskers.
-        showbox : bool, default: True
-            Show the central box.
-        showfliers : bool, default: True
-            Show the outliers beyond the caps.
-        showmeans : bool, default: False
-            Show the arithmetic means.
-        capprops : dict, default: None
-            The style of the caps.
-        boxprops : dict, default: None
-            The style of the box.
-        whiskerprops : dict, default: None
-            The style of the whiskers.
-        flierprops : dict, default: None
-            The style of the fliers.
-        medianprops : dict, default: None
-            The style of the median.
-        meanprops : dict, default: None
-            The style of the mean.
-
         Returns
         -------
         result : dict
@@ -3648,6 +3625,29 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
 
           - ``means``: points or lines representing the means.
 
+        Other Parameters
+        ----------------
+        showcaps : bool, default: True
+            Show the caps on the ends of whiskers.
+        showbox : bool, default: True
+            Show the central box.
+        showfliers : bool, default: True
+            Show the outliers beyond the caps.
+        showmeans : bool, default: False
+            Show the arithmetic means.
+        capprops : dict, default: None
+            The style of the caps.
+        boxprops : dict, default: None
+            The style of the box.
+        whiskerprops : dict, default: None
+            The style of the whiskers.
+        flierprops : dict, default: None
+            The style of the fliers.
+        medianprops : dict, default: None
+            The style of the median.
+        meanprops : dict, default: None
+            The style of the mean.
+
         """
 
         # Missing arguments default to rcParams.
@@ -4550,6 +4550,20 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
 
             Order of scalars is (left, right, bottom, top).
 
+        Returns
+        -------
+        polycollection : `~matplotlib.collections.PolyCollection`
+            A `.PolyCollection` defining the hexagonal bins.
+
+            - `.PolyCollection.get_offset` contains a Mx2 array containing
+              the x, y positions of the M hexagon centers.
+            - `.PolyCollection.get_array` contains the values of the M
+              hexagons.
+
+            If *marginals* is *True*, horizontal
+            bar and vertical bar (both PolyCollections) will be attached
+            to the return collection as attributes *hbar* and *vbar*.
+
         Other Parameters
         ----------------
         cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
@@ -4600,20 +4614,6 @@ def reduce_C_function(C: array) -> float
 
             %(PolyCollection)s
 
-        Returns
-        -------
-        polycollection : `~matplotlib.collections.PolyCollection`
-            A `.PolyCollection` defining the hexagonal bins.
-
-            - `.PolyCollection.get_offset` contains a Mx2 array containing
-              the x, y positions of the M hexagon centers.
-            - `.PolyCollection.get_array` contains the values of the M
-              hexagons.
-
-            If *marginals* is *True*, horizontal
-            bar and vertical bar (both PolyCollections) will be attached
-            to the return collection as attributes *hbar* and *vbar*.
-
         """
         self._process_unit_info(xdata=x, ydata=y, kwargs=kwargs)
 
@@ -5119,6 +5119,11 @@ def _fill_between_x_or_y(
               value ``y[i]``.
             - 'mid': Steps occur half-way between the *x* positions.
 
+        Returns
+        -------
+        `.PolyCollection`
+            A `.PolyCollection` containing the plotted polygons.
+
         Other Parameters
         ----------------
         **kwargs
@@ -5127,11 +5132,6 @@ def _fill_between_x_or_y(
 
             %(PolyCollection)s
 
-        Returns
-        -------
-        `.PolyCollection`
-            A `.PolyCollection` containing the plotted polygons.
-
         See Also
         --------
         fill_between : Fill between two sets of y-values.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -3465,7 +3465,7 @@ def set_xticklabels(self, labels, fontdict=None, minor=False, **kwargs):
             The labels.
 
         Other Parameters
-        -----------------
+        ----------------
         **kwargs : `~.text.Text` properties.
         """
         if fontdict is not None:
diff --git a/lib/matplotlib/axes/_secondary_axes.py b/lib/matplotlib/axes/_secondary_axes.py
@@ -374,14 +374,13 @@ def set_color(self, color):
     See :doc:`/gallery/subplots_axes_and_figures/secondary_axis`
     for examples of making these conversions.
 
+Returns
+-------
+ax : axes._secondary_axes.SecondaryAxis
 
 Other Parameters
 ----------------
 **kwargs : `~matplotlib.axes.Axes` properties.
     Other miscellaneous axes parameters.
-
-Returns
--------
-ax : axes._secondary_axes.SecondaryAxis
 '''
 docstring.interpd.update(_secax_docstring=_secax_docstring)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1142,6 +1142,14 @@ def add_axes(self, *args, **kwargs):
         label : str
             A label for the returned axes.
 
+        Returns
+        -------
+        axes : `~.axes.Axes` (or a subclass of `~.axes.Axes`)
+            The returned axes class depends on the projection used. It is
+            `~.axes.Axes` if rectilinear projection are used and
+            `.projections.polar.PolarAxes` if polar projection
+            are used.
+
         Other Parameters
         ----------------
         **kwargs
@@ -1154,14 +1162,6 @@ def add_axes(self, *args, **kwargs):
 
             %(Axes)s
 
-        Returns
-        -------
-        axes : `~.axes.Axes` (or a subclass of `~.axes.Axes`)
-            The returned axes class depends on the projection used. It is
-            `~.axes.Axes` if rectilinear projection are used and
-            `.projections.polar.PolarAxes` if polar projection
-            are used.
-
         Notes
         -----
         If the figure already has an axes with key (*args*,
@@ -1290,6 +1290,16 @@ def add_subplot(self, *args, **kwargs):
         label : str
             A label for the returned axes.
 
+        Returns
+        -------
+        axes : `.axes.SubplotBase`, or another subclass of `~.axes.Axes`
+
+            The axes of the subplot. The returned axes base class depends on
+            the projection used. It is `~.axes.Axes` if rectilinear projection
+            are used and `.projections.polar.PolarAxes` if polar projection
+            are used. The returned axes is then a subplot subclass of the
+            base class.
+
         Other Parameters
         ----------------
         **kwargs
@@ -1301,16 +1311,6 @@ def add_subplot(self, *args, **kwargs):
 
             %(Axes)s
 
-        Returns
-        -------
-        axes : `.axes.SubplotBase`, or another subclass of `~.axes.Axes`
-
-            The axes of the subplot. The returned axes base class depends on
-            the projection used. It is `~.axes.Axes` if rectilinear projection
-            are used and `.projections.polar.PolarAxes` if polar projection
-            are used. The returned axes is then a subplot subclass of the
-            base class.
-
         Notes
         -----
         If the figure already has a subplot with key (*args*,
@@ -1788,14 +1788,14 @@ def legend(self, *args, **kwargs):
             is shown in the legend and the automatic mechanism described above
             is not sufficient.
 
-        Other Parameters
-        ----------------
-        %(_legend_kw_doc)s
-
         Returns
         -------
         `~matplotlib.legend.Legend`
 
+        Other Parameters
+        ----------------
+        %(_legend_kw_doc)s
+
         Notes
         -----
         Some artists are not supported by this function.  See
@@ -1843,17 +1843,17 @@ def text(self, x, y, s, fontdict=None, **kwargs):
             the defaults are determined by :rc:`font.*`. Properties passed as
             *kwargs* override the corresponding ones given in *fontdict*.
 
+        Returns
+        -------
+        text : `~.text.Text`
+
         Other Parameters
         ----------------
         **kwargs : `~matplotlib.text.Text` properties
             Other miscellaneous text parameters.
 
             %(Text)s
 
-        Returns
-        -------
-        text : `~.text.Text`
-
         See Also
         --------
         .Axes.text
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -789,6 +789,14 @@ def axes(arg=None, **kwargs):
     label : str
         A label for the returned axes.
 
+    Returns
+    -------
+    axes : `~.axes.Axes` (or a subclass of `~.axes.Axes`)
+        The returned axes class depends on the projection used. It is
+        `~.axes.Axes` if rectilinear projection are used and
+        `.projections.polar.PolarAxes` if polar projection
+        are used.
+
     Other Parameters
     ----------------
     **kwargs
@@ -801,14 +809,6 @@ def axes(arg=None, **kwargs):
 
         %(Axes)s
 
-    Returns
-    -------
-    axes : `~.axes.Axes` (or a subclass of `~.axes.Axes`)
-        The returned axes class depends on the projection used. It is
-        `~.axes.Axes` if rectilinear projection are used and
-        `.projections.polar.PolarAxes` if polar projection
-        are used.
-
     Notes
     -----
     If the figure already has a axes with key (*args*,
@@ -914,17 +914,6 @@ def subplot(*args, **kwargs):
     label : str
         A label for the returned axes.
 
-    Other Parameters
-    ----------------
-    **kwargs
-        This method also takes the keyword arguments for the returned axes
-        base class; except for the *figure* argument. The keyword arguments
-        for the rectilinear base class `~.axes.Axes` can be found in
-        the following table but there might also be other keyword
-        arguments if another projection is used.
-
-        %(Axes)s
-
     Returns
     -------
     axes : an `.axes.SubplotBase` subclass of `~.axes.Axes` (or a subclass \
@@ -936,6 +925,17 @@ def subplot(*args, **kwargs):
         are used. The returned axes is then a subplot subclass of the
         base class.
 
+    Other Parameters
+    ----------------
+    **kwargs
+        This method also takes the keyword arguments for the returned axes
+        base class; except for the *figure* argument. The keyword arguments
+        for the rectilinear base class `~.axes.Axes` can be found in
+        the following table but there might also be other keyword
+        arguments if another projection is used.
+
+        %(Axes)s
+
     Notes
     -----
     Creating a subplot will delete any pre-existing subplot that overlaps
diff --git a/lib/matplotlib/table.py b/lib/matplotlib/table.py
