Document the legend argument of categorical scatterplots

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)"
    ]
   },
   {

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)"
    ]
   },
   {

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
+)

seaborn/categorical.py

@@ -2133,6 +2133,10 @@ def plot(self, ax, boxplot_kws):
         Function for converting categorical data into strings. Affects both grouping
         and tick labels.\
     """),
+    legend=dedent("""\
+    legend : str or bool, optional
+        If `False` or an empty string and `hue` is used, don't draw a legend.
+    """),
     ax_in=dedent("""\
     ax : matplotlib Axes, optional
         Axes object to draw the plot onto, otherwise uses the current Axes.\
@@ -2542,6 +2546,7 @@ def stripplot(
     {linewidth}
     {native_scale}
     {formatter}
+    {legend}
     {ax_in}
     kwargs : key, value mappings
         Other keyword arguments are passed through to
@@ -2663,6 +2668,7 @@ def swarmplot(
     {linewidth}
     {native_scale}
     {formatter}
+    {legend}
     {ax_in}
     kwargs : key, value mappings
         Other keyword arguments are passed through to
@@ -3272,7 +3278,7 @@ def catplot(
     {color}
     {palette}
     {hue_norm}
-    legend : bool, optional
+    legend : str or bool, optional
         If ``True`` and there is a ``hue`` variable, draw a legend on the plot.
     {legend_out}
     {share_xy}