From f80ff7bc3d60661c8b1ec749730c5b41196a4976 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Thu, 4 Jan 2018 13:00:37 +0100
Subject: [PATCH] improve Axes.broken_barh docstring

---
 lib/matplotlib/axes/_axes.py | 56 ++++++++++++++++++++++++------------
 1 file changed, 38 insertions(+), 18 deletions(-)

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index 3f040410d58c..26135ba28615 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -2340,33 +2340,53 @@ def barh(self, *args, **kwargs):
     @docstring.dedent_interpd
     def broken_barh(self, xranges, yrange, **kwargs):
         """
-        Plot horizontal bars.
+        Plot a horizontal sequence of rectangles.
 
-        A collection of horizontal bars spanning *yrange* with a sequence of
-        *xranges*.
+        A rectangle is drawn for each element of *xranges*. All rectangles
+        have the same vertical position and size defined by *yrange*.
 
-        Required arguments:
+        This is a convenience function for instantiating a
+        `.BrokenBarHCollection`, adding it to the axes and autoscaling the
+        view.
 
-          =========   ==============================
-          Argument    Description
-          =========   ==============================
-          *xranges*   sequence of (*xmin*, *xwidth*)
-          *yrange*    sequence of (*ymin*, *ywidth*)
-          =========   ==============================
+        Parameters
+        ----------
+        xranges : sequence of tuples (*xmin*, *xwidth*)
+            The x-positions and extends of the rectangles. For each tuple
+            (*xmin*, *xwidth*) a rectangle is drawn from *xmin* to *xmin* +
+            *xwidth*.
+        yranges : (*ymin*, *ymax*)
+            The y-position and extend for all the rectangles.
 
-        kwargs are
-        :class:`matplotlib.collections.BrokenBarHCollection`
-        properties:
+        Other Parameters
+        ----------------
+        **kwargs : :class:`~.BrokenBarHCollection` properties
+
+            Each *kwarg* can be either a single argument applying to all
+            rectangles, e.g.::
+
+                facecolors='black'
 
-        %(BrokenBarHCollection)s
+            or a sequence of arguments over which is cycled, e.g.::
 
-        these can either be a single argument, i.e.,::
+                facecolors=('black', 'blue')
 
-          facecolors = 'black'
+            would create interleaving black and blue rectangles.
 
-        or a sequence of arguments for the various bars, i.e.,::
+            Supported keywords:
+
+            %(BrokenBarHCollection)s
+
+        Returns
+        -------
+        :class:`matplotlib.collections.BrokenBarHCollection`
+
+        Notes
+        -----
+        ..
+            [Empty notes is a workaround to prevent the data note from being
+            injected into the  Returns section.]
 
-          facecolors = ('black', 'red', 'green')
         """
         # process the unit information
         if len(xranges):