DOC: clarify the default value of *radius* in Patch.contains_point (#27462)

tacaswell · oscargus · QuLogic · web-flow · commit 2fa85ee57467 · 2024-02-17T18:46:03.000+01:00
... and friends. closes #19807 Co-authored-by: Oscar Gustafsson <oscar.gustafsson@gmail.com> Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com> Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -127,6 +127,29 @@ def contains(self, mouseevent, radius=None):
         """
         Test whether the mouse event occurred in the patch.
 
+        Parameters
+        ----------
+        mouseevent : `~matplotlib.backend_bases.MouseEvent`
+            Where the user clicked.
+
+        radius : float, optional
+            Additional margin on the patch in target coordinates of
+            `.Patch.get_transform`. See `.Path.contains_point` for further
+            details.
+
+            If `None`, the default value depends on the state of the object:
+
+            - If `.Artist.get_picker` is a number, the default
+              is that value.  This is so that picking works as expected.
+            - Otherwise if the edge color has a non-zero alpha, the default
+              is half of the linewidth.  This is so that all the colored
+              pixels are "in" the patch.
+            - Finally, if the edge has 0 alpha, the default is 0.  This is
+              so that patches without a stroked edge do not have points
+              outside of the filled region report as "in" due to an
+              invisible edge.
+
+
         Returns
         -------
         (bool, empty dict)
@@ -160,13 +183,25 @@ def contains_point(self, point, radius=None):
         ----------
         point : (float, float)
             The point (x, y) to check, in target coordinates of
-            ``self.get_transform()``. These are display coordinates for patches
+            ``.Patch.get_transform()``. These are display coordinates for patches
             that are added to a figure or Axes.
         radius : float, optional
             Additional margin on the patch in target coordinates of
-            ``self.get_transform()``. See `.Path.contains_point` for further
+            `.Patch.get_transform`. See `.Path.contains_point` for further
             details.
 
+            If `None`, the default value depends on the state of the object:
+
+            - If `.Artist.get_picker` is a number, the default
+              is that value.  This is so that picking works as expected.
+            - Otherwise if the edge color has a non-zero alpha, the default
+              is half of the linewidth.  This is so that all the colored
+              pixels are "in" the patch.
+            - Finally, if the edge has 0 alpha, the default is 0.  This is
+              so that patches without a stroked edge do not have points
+              outside of the filled region report as "in" due to an
+              invisible edge.
+
         Returns
         -------
         bool
@@ -214,9 +249,21 @@ def contains_points(self, points, radius=None):
             that are added to a figure or Axes. Columns contain x and y values.
         radius : float, optional
             Additional margin on the patch in target coordinates of
-            ``self.get_transform()``. See `.Path.contains_point` for further
+            `.Patch.get_transform`. See `.Path.contains_point` for further
             details.
 
+            If `None`, the default value depends on the state of the object:
+
+            - If `.Artist.get_picker` is a number, the default
+              is that value.  This is so that picking works as expected.
+            - Otherwise if the edge color has a non-zero alpha, the default
+              is half of the linewidth.  This is so that all the colored
+              pixels are "in" the patch.
+            - Finally, if the edge has 0 alpha, the default is 0.  This is
+              so that patches without a stroked edge do not have points
+              outside of the filled region report as "in" due to an
+              invisible edge.
+
         Returns
         -------
         length-N bool array
