Merge pull request #15216 from timhoffm/doc-contains-point

tacaswell · web-flow · commit 8c6861764270 · 2019-09-07T16:51:08.000-04:00
DOC: Update docstrings of contains_point(s) methods
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -154,10 +154,47 @@ def contains(self, mouseevent, radius=None):
 
     def contains_point(self, point, radius=None):
         """
-        Returns ``True`` if the given *point* is inside the path
-        (transformed with its transform attribute).
+        Return whether the given point is inside the patch.
+
+        Parameters
+        ----------
+        point : (float, float)
+            The point (x, y) to check in target coordinates of
+            ``self.get_transform()``. For patches added to a figure or axes,
+            these are display coordinates.
+        radius : float, optional
+            Adds an additional margin on the patch in coordinates of transform.
+            target. See `.Path.contains_point` for further details.
+
+        Returns
+        -------
+        bool
+
+        Notes
+        -----
+        The proper use of this method depends on the transform of the patch.
+        Isolated patches do not have a transform. In this, the patch creation
+        coordinates and the point coordinates match. The follow checks that
+        the center of a circle is within the circle
+
+        >>> center = 0, 0
+        >>> c = Circle(center, radius=1)
+        >>> c.contains_point(center)
+        True
+
+        The convention of checking against the transformed patch stems from
+        the fact that this method is predominantly used to check if display
+        coordinates (e.g. from mouse events) are within the patch. If you want
+        to do the above check with data coordinates, you have to properly
+        transform them first:
+
+        >>> center = 0, 0
+        >>> c = Circle(center, radius=1)
+        >>> plt.gca().add_patch(c)
+        >>> transformed_center = c.get_transform().transform(center)
+        >>> c.contains_point(transformed_center)
+        True
 
-        *radius* allows the path to be made slightly larger or smaller.
         """
         radius = self._process_radius(radius)
         return self.get_path().contains_point(point,
@@ -166,12 +203,26 @@ def contains_point(self, point, radius=None):
 
     def contains_points(self, points, radius=None):
         """
-        Returns a bool array which is ``True`` if the (closed) path
-        contains the corresponding point.
-        (transformed with its transform attribute).
+        Return whether the given points are inside the patch.
 
-        *points* must be Nx2 array.
-        *radius* allows the path to be made slightly larger or smaller.
+        Parameters
+        ----------
+        points : (N, 2) array
+            The points to check in target coordinates of
+            ``self.get_transform()``. For patches added to a figure or axes,
+            these are display coordinates. Columns contain x and y values.
+        radius : float, optional
+            Adds an additional margin on the patch in coordinates of transform.
+            target. See `.Path.contains_points` for further details.
+
+        Returns
+        -------
+        length-N bool array
+
+        Notes
+        -----
+        The proper use of this method depends on the transform of the patch.
+        See the notes on `.Patch.contains_point`.
         """
         radius = self._process_radius(radius)
         return self.get_path().contains_points(points,
diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py
@@ -450,12 +450,27 @@ def transformed(self, transform):
 
     def contains_point(self, point, transform=None, radius=0.0):
         """
-        Returns whether the (closed) path contains the given point.
+        Return whether the (closed) path contains the given point.
 
-        If *transform* is not ``None``, the path will be transformed before
-        performing the test.
-
-        *radius* allows the path to be made slightly larger or smaller.
+        Parameters
+        ----------
+        point : (float, float)
+            The point (x, y) to check.
+        transform : `matplotlib.transforms.Transform`, optional
+            If not ``None``, *point* will be compared to self transformed
+            by *transform*; i.e. for a correct check, *transform* should
+            transform the path into the coordinate system of *point*.
+        radius : float, default: 0.
+            Adds an additional margin on the path in coordinates of *point*.
+            The path is extended tangentially by *radius/2*; i.e. if you would
+            draw the path with a linewidth of *radius*, all points on the line
+            would still be considered to be contained in the area. Conversely,
+            negative values shrink the area; points on the imaginary line
+            will be considered outside the area.
+
+        Returns
+        -------
+        bool
         """
         if transform is not None:
             transform = transform.frozen()
@@ -470,13 +485,27 @@ def contains_point(self, point, transform=None, radius=0.0):
 
     def contains_points(self, points, transform=None, radius=0.0):
         """
-        Returns a bool array which is ``True`` if the (closed) path contains
-        the corresponding point.
+        Return whether the (closed) path contains the given point.
 
-        If *transform* is not ``None``, the path will be transformed before
-        performing the test.
-
-        *radius* allows the path to be made slightly larger or smaller.
+        Parameters
+        ----------
+        points : (N, 2) array
+            The points to check. Columns contain x and y values.
+        transform : `matplotlib.transforms.Transform`, optional
+            If not ``None``, *points* will be compared to self transformed
+            by *transform*; i.e. for a correct check, *transform* should
+            transform the path into the coordinate system of *points*.
+        radius : float, default: 0.
+            Adds an additional margin on the path in coordinates of *points*.
+            The path is extended tangentially by *radius/2*; i.e. if you would
+            draw the path with a linewidth of *radius*, all points on the line
+            would still be considered to be contained in the area. Conversely,
+            negative values shrink the area; points on the imaginary line
+            will be considered outside the area.
+
+        Returns
+        -------
+        length-N bool array
         """
         if transform is not None:
             transform = transform.frozen()
