Apply suggestions from code review

timhoffm · story645 · timhoffm · commit 7cf1e6bf49c1 · 2025-01-24T00:34:23.000+01:00
Co-authored-by: hannah &lt;story645@gmail.com&gt;
diff --git a/doc/users/next_whats_new/grouped_bar.rst b/doc/users/next_whats_new/grouped_bar.rst
@@ -10,6 +10,7 @@ Example:
 
 .. plot::
     :include-source: true
+    :alt: Diagram of a grouped bar chart of 3 datasets with 2 categories.
 
     import matplotlib.pyplot as plt
 
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -3077,18 +3077,14 @@ def grouped_bar(self, heights, *, positions=None, group_spacing=1.5, bar_spacing
             This function is new in v3.11, and the API is still provisional.
             We may still fine-tune some aspects based on user-feedback.
 
-        This is a convenience function to plot bars for multiple datasets.
-        In particular, it simplifies positioning of the bars compared to individual
-        `~.Axes.bar` plots.
-
         Bar plots present categorical data as a sequence of bars, one bar per category.
-        We call one set of such values a *dataset* and it's bars all share the same
+        We call one set of such values a *dataset* and its bars all share the same
         color. Grouped bar plots show multiple such datasets, where the values per
         category are grouped together. The category names are drawn as tick labels
         below the bar groups. Each dataset has a distinct bar color, and can optionally
         get a label that is used for the legend.
 
-        Here is an example call structure and the corresponding plot:
+        Example:
 
         .. code-block:: python
 
@@ -3098,6 +3094,10 @@ def grouped_bar(self, heights, *, positions=None, group_spacing=1.5, bar_spacing
 
         .. plot:: _embedded_plots/grouped_bar.py
 
+        ``grouped_bar()`` is a high-level plotting function for grouped bar charts.
+        Use `~.Axes.bar` instead if you need finer grained control on individual bar
+        positions or widths.
+
         Parameters
         ----------
         heights : list of array-like or dict of array-like or 2D array \
@@ -3121,9 +3121,6 @@ def grouped_bar(self, heights, *, positions=None, group_spacing=1.5, bar_spacing
             - dict of array-like: A mapping from names to datasets. Each dataset
               (dict value) must have the same number of elements.
 
-              This is similar to passing a list of array-like, with the addition that
-              each dataset gets a name.
-
               Example call:
 
               .. code-block:: python
@@ -3154,21 +3151,16 @@ def grouped_bar(self, heights, *, positions=None, group_spacing=1.5, bar_spacing
 
               .. code-block:: python
 
-                  group_labels = ["group_A", "group_B"]
+                  categories = ["A", "B"]
                   dataset_labels = ["dataset_0", "dataset_1", "dataset_2"]
                   array = np.random.random((2, 3))
-
-              Note that this is consistent with pandas. These two calls produce
-              the same bar plot structure:
-
-              .. code-block:: python
-
                   grouped_bar(array, tick_labels=categories, labels=dataset_labels)
-                  df = pd.DataFrame(array, index=categories, columns=dataset_labels)
-                  df.plot.bar()
 
             - a `pandas.DataFrame`.
 
+              The index is used for the categories, the columns are used for the
+              datasets.
+
               .. code-block:: python
 
                   df = pd.DataFrame(
@@ -3178,6 +3170,9 @@ def grouped_bar(self, heights, *, positions=None, group_spacing=1.5, bar_spacing
                   )
                   grouped_bar(df)
 
+                  # is equivalent to
+                  grouped_bar(df.to_numpy(), tick_labels=df.index, labels=df.columns)
+
               Note that ``grouped_bar(df)`` produces a structurally equivalent plot like
               ``df.plot.bar()``.
 
@@ -3187,9 +3182,8 @@ def grouped_bar(self, heights, *, positions=None, group_spacing=1.5, bar_spacing
 
         tick_labels : list of str, optional
             The category labels, which are placed on ticks at the center *positions*
-            of the bar groups.
-
-            If not set, the axis ticks (positions and labels) are left unchanged.
+            of the bar groups. If not set, the axis ticks (positions and labels) are
+            left unchanged.
 
         labels : list of str, optional
             The labels of the datasets, i.e. the bars within one group.
