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

... and friends.

closes matplotlib#19807

Co-authored-by: Oscar Gustafsson <[email protected]>
Co-authored-by: Elliott Sales de Andrade <[email protected]>
Co-authored-by: Tim Hoffmann <[email protected]>

Author: 4 people

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