From 3f08f3826072a970343ca490d311b85256a49ab9 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Fri, 24 Jan 2025 12:44:05 +0100
Subject: [PATCH 1/2] DOC: Document the behavior of bar() for categorical x
 data

In particular, mention the different behavior on duplicates compared to using `tick_label` explicitly.

Closes #29507.
---
 lib/matplotlib/axes/_axes.py | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index c4967025e136..f3863258dd30 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -2386,6 +2386,17 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
             The x coordinates of the bars. See also *align* for the
             alignment of the bars to the coordinates.
 
+            Bars are often used for categorical data, i.e. string labels below
+            the bars. You can provide a list of strings directly to *x*.
+            ``bar(['A', 'B', 'C'], [1, 2, 3])`` is often a shorter and more
+            convenient notation compared to
+            ``bar(range(3), [1, 2, 3], tick_label=['A', 'B', 'C'])``. They are
+            equivalent as long as the names are unique. The explicit *tick_label*
+            notation draws the names in the sequence given. However, when having
+            duplicate values in categorical *x* data, these values map to the same
+            numerical x coordinate, and hence the corresponding bars are drawn on
+            top of each other.
+
         height : float or array-like
             The height(s) of the bars.
 
@@ -2701,6 +2712,17 @@ def barh(self, y, width, height=0.8, left=None, *, align="center",
             The y coordinates of the bars. See also *align* for the
             alignment of the bars to the coordinates.
 
+            Bars are often used for categorical data, i.e. string labels below
+            the bars. You can provide a list of strings directly to *y*.
+            ``bar(['A', 'B', 'C'], [1, 2, 3])`` is often a shorter and more
+            convenient notation compared to
+            ``bar(range(3), [1, 2, 3], tick_label=['A', 'B', 'C'])``. They are
+            equivalent as long as the names are unique. The explicit *tick_label*
+            notation draws the names in the sequence given. However, when having
+            duplicate values in categorical *y* data, these values map to the same
+            numerical y coordinate, and hence the corresponding bars are drawn on
+            top of each other.
+
         width : float or array-like
             The width(s) of the bars.
 

From a61e5922f25f0ad94b369ed15b8e17d81036b05d Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Fri, 24 Jan 2025 14:49:41 +0100
Subject: [PATCH 2/2] Update lib/matplotlib/axes/_axes.py

Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>
---
 lib/matplotlib/axes/_axes.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index f3863258dd30..608913a3e62b 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -2714,9 +2714,9 @@ def barh(self, y, width, height=0.8, left=None, *, align="center",
 
             Bars are often used for categorical data, i.e. string labels below
             the bars. You can provide a list of strings directly to *y*.
-            ``bar(['A', 'B', 'C'], [1, 2, 3])`` is often a shorter and more
+            ``barh(['A', 'B', 'C'], [1, 2, 3])`` is often a shorter and more
             convenient notation compared to
-            ``bar(range(3), [1, 2, 3], tick_label=['A', 'B', 'C'])``. They are
+            ``barh(range(3), [1, 2, 3], tick_label=['A', 'B', 'C'])``. They are
             equivalent as long as the names are unique. The explicit *tick_label*
             notation draws the names in the sequence given. However, when having
             duplicate values in categorical *y* data, these values map to the same