From ff96e1f0f1b54074f6f4dc5976bdfb4f19646851 Mon Sep 17 00:00:00 2001
From: Maoz Gelbart <13831112+MaozGelbart@users.noreply.github.com>
Date: Wed, 3 Aug 2022 05:29:28 +0300
Subject: [PATCH] Document the legend argument of categorical scatterplots
 (#2933)

* Simplify jitter stripplot example

* Document the legend argument

* Demonstrate 0.11 legend behavior in docstrings

* Include more info on legend for numeric variables

* Include more info on legend for numeric variables

Co-authored-by: Michael Waskom <mwaskom@users.noreply.github.com>
---
 doc/_docstrings/stripplot.ipynb |  2 +-
 doc/_docstrings/swarmplot.ipynb |  2 +-
 examples/jitter_stripplot.py    | 10 +++++-----
 seaborn/categorical.py          | 15 +++++++++++++--
 4 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/doc/_docstrings/stripplot.ipynb b/doc/_docstrings/stripplot.ipynb
index 0dbe3f14d2..34264355a7 100644
--- a/doc/_docstrings/stripplot.ipynb
+++ b/doc/_docstrings/stripplot.ipynb
@@ -76,7 +76,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.stripplot(data=tips, x=\"total_bill\", y=\"day\", hue=\"day\")"
+    "sns.stripplot(data=tips, x=\"total_bill\", y=\"day\", hue=\"day\", legend=False)"
    ]
   },
   {
diff --git a/doc/_docstrings/swarmplot.ipynb b/doc/_docstrings/swarmplot.ipynb
index e5f6d9e916..3ad69287f3 100644
--- a/doc/_docstrings/swarmplot.ipynb
+++ b/doc/_docstrings/swarmplot.ipynb
@@ -76,7 +76,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sns.swarmplot(data=tips, x=\"total_bill\", y=\"day\", hue=\"day\")"
+    "sns.swarmplot(data=tips, x=\"total_bill\", y=\"day\", hue=\"day\", legend=False)"
    ]
   },
   {
diff --git a/examples/jitter_stripplot.py b/examples/jitter_stripplot.py
index e5abf78ce3..a0f6ae6c1d 100644
--- a/examples/jitter_stripplot.py
+++ b/examples/jitter_stripplot.py
@@ -19,7 +19,8 @@
 
 # Show each observation with a scatterplot
 sns.stripplot(x="value", y="measurement", hue="species",
-              data=iris, dodge=True, alpha=.25, zorder=1)
+              data=iris, dodge=True, alpha=.25, zorder=1,
+              legend=False)
 
 # Show the conditional means, aligning each pointplot in the
 # center of the strips by adjusting the width allotted to each
@@ -30,7 +31,6 @@
               markers="d", scale=.75, ci=None)
 
 # Improve the legend
-handles, labels = ax.get_legend_handles_labels()
-ax.legend(handles[3:], labels[3:], title="species",
-          handletextpad=0, columnspacing=1,
-          loc="lower right", ncol=3, frameon=True)
+sns.move_legend(
+    ax, loc="lower right", ncol=3, frameon=True, columnspacing=1, handletextpad=0
+)
diff --git a/seaborn/categorical.py b/seaborn/categorical.py
index fe2c6fd1e2..0305a08b1e 100644
--- a/seaborn/categorical.py
+++ b/seaborn/categorical.py
@@ -2133,6 +2133,14 @@ def plot(self, ax, boxplot_kws):
         Function for converting categorical data into strings. Affects both grouping
         and tick labels.\
     """),
+    legend=dedent("""\
+legend : "auto", "brief", "full", or False
+    How to draw the legend. If "brief", numeric `hue` and `size`
+    variables will be represented with a sample of evenly spaced values.
+    If "full", every group will get an entry in the legend. If "auto",
+    choose between brief or full representation based on number of levels.
+    If `False`, no legend data is added and no legend is drawn.
+    """),
     ax_in=dedent("""\
     ax : matplotlib Axes, optional
         Axes object to draw the plot onto, otherwise uses the current Axes.\
@@ -2542,6 +2550,7 @@ def stripplot(
     {linewidth}
     {native_scale}
     {formatter}
+    {legend}
     {ax_in}
     kwargs : key, value mappings
         Other keyword arguments are passed through to
@@ -2663,6 +2672,7 @@ def swarmplot(
     {linewidth}
     {native_scale}
     {formatter}
+    {legend}
     {ax_in}
     kwargs : key, value mappings
         Other keyword arguments are passed through to
@@ -3272,8 +3282,9 @@ def catplot(
     {color}
     {palette}
     {hue_norm}
-    legend : bool, optional
-        If ``True`` and there is a ``hue`` variable, draw a legend on the plot.
+    legend : str or bool, optional
+        Set to `False` to disable the legend. With `strip` or `swarm` plots,
+        this also accepts a string, as described in the axes-level docstrings.
     {legend_out}
     {share_xy}
     {margin_titles}