DOC: add a note about linewidth to scatter docs

tacaswell · QuLogic · tacaswell · commit 6064a2e6f6d4 · 2023-03-31T15:42:41.000-04:00
closes matplotlib#25410 Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -4478,6 +4478,20 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
             The marker size in points**2 (typographic points are 1/72 in.).
             Default is ``rcParams['lines.markersize'] ** 2``.
 
+            The linewidth and edgecolor can visually interact with the marker
+            size.
+
+            If the linewidth is greater than 0 and the edegecolor is anything
+            but *'none'*, then the effective size of the marker will be
+            increased by half the linewidth as the stroke drawn for the edge
+            will be centered on the edge of the shape.
+
+            If the marker size is smaller than the linewidth there will be
+            visual artifacts.
+
+            To eliminate the marker edge either set *linewidth=0* or
+            *edgecolor='none'*.
+
         c : array-like or list of colors or color, optional
             The marker colors. Possible values:
 
