matplotlib
diff --git a/‎lib/matplotlib/bezier.py
Copy file name to clipboardExpand all lines: lib/matplotlib/bezier.py
+94-32Lines changed: 94 additions & 32 deletions b/‎lib/matplotlib/bezier.py
Copy file name to clipboardExpand all lines: lib/matplotlib/bezier.py
+94-32Lines changed: 94 additions & 32 deletions
@@ -18,7 +18,7 @@ def get_intersection(cx1, cy1, cos_t1, sin_t1,
                      cx2, cy2, cos_t2, sin_t2):
     """
     Return the intersection between the line through (*cx1*, *cy1*) at angle
-    *t1* and the line through (*cx2, cy2) at angle *t2*.
+    *t1* and the line through (*cx2*, *cy2*) at angle *t2*.
     """
 
     # line1 => sin_t1 * (x - cx1) - cos_t1 * (y - cy1) = 0.
@@ -49,7 +49,7 @@ def get_intersection(cx1, cy1, cos_t1, sin_t1,
 
 def get_normal_points(cx, cy, cos_t, sin_t, length):
     """
-    For a line passing through (*cx*, *cy*) and having a angle *t*, return
+    For a line passing through (*cx*, *cy*) and having an angle *t*, return
     locations of the two points located along its perpendicular line at the
     distance of *length*.
     """
@@ -99,21 +99,41 @@ def split_de_casteljau(beta, t):
 def find_bezier_t_intersecting_with_closedpath(
         bezier_point_at_t, inside_closedpath, t0=0., t1=1., tolerance=0.01):
     """
-    Find a parameter t0 and t1 of the given bezier path which
-    bounds the intersecting points with a provided closed
-    path(*inside_closedpath*). Search starts from *t0* and *t1* and it
-    uses a simple bisecting algorithm therefore one of the end point
-    must be inside the path while the other doesn't. The search stop
-    when |t0-t1| gets smaller than the given tolerance.
-    value for
+    Find the intersection of the bezier curve with a closed path.
 
-    - bezier_point_at_t : a function which returns x, y coordinates at *t*
+    The intersection point *t* is approximated by two parameters *t0*, *t1*
+    such that *t0* <= *t* <= *t1*.
 
-    - inside_closedpath : return True if the point is inside the path
+    Search starts from *t0* and *t1* and it uses a simple bisecting algorithm
+    therefore one of the end points must be inside the path while the other
+    doesn't. The search stops when the distance of the points parametrized by
+    *t0* and *t1* gets smaller than the given *tolerance*.
 
-    """
-    # inside_closedpath : function
+    Parameters
+    ----------
+    bezier_point_at_t : callable
+        A function returning x, y coordinates of the bezier at parameter *t*.
+        it must have the signature::
+
+            bezier_point_at_t(t: float) -> Tuple[float, float]
+
+    inside_closedpath : callable
+        A function returning True if a given point (x, y) is inside the
+        closed path. It must have the signature::
+
+            inside_closedpath(point: Tuple[float, float]) -> bool
 
+    t0, t1 : float
+        Start parameters for the search.
+
+    tolerance : float
+        Maximal allowed distance between the final points.
+
+    Returns
+    -------
+    t0, t1 : float
+        The bezier path parameters.
+    """
     start = bezier_point_at_t(t0)
     end = bezier_point_at_t(t1)
 
@@ -147,21 +167,22 @@ def find_bezier_t_intersecting_with_closedpath(
 
 class BezierSegment:
     """
-    A simple class of a 2-dimensional bezier segment
+    A 2-dimensional bezier segment.
+
+    Parameters
+    ----------
+    control_points : array-like (N, 2)
+        A list of the (x, y) positions of contol points of the bezier line.
+        This must contain N points ,where N is the order of the bezier line.
+        1<= N <= 3 is supported.
     """
-
     # Higher order bezier lines can be supported by simplying adding
     # corresponding values.
     _binom_coeff = {1: np.array([1., 1.]),
                     2: np.array([1., 2., 1.]),
                     3: np.array([1., 3., 3., 1.])}
 
     def __init__(self, control_points):
-        """
-        *control_points* : location of contol points. It needs have a
-         shape of n * 2, where n is the order of the bezier line. 1<=
-         n <= 3 is supported.
-        """
         _o = len(control_points)
         self._orders = np.arange(_o)
 
@@ -171,7 +192,7 @@ def __init__(self, control_points):
         self._py = yy * _coeff
 
     def point_at_t(self, t):
-        "evaluate a point at t"
+        """Return the point (x, y) at parameter *t*."""
         tt = ((1 - t) ** self._orders)[::-1] * t ** self._orders
         _x = np.dot(tt, self._px)
         _y = np.dot(tt, self._py)
@@ -182,9 +203,23 @@ def point_at_t(self, t):
 def split_bezier_intersecting_with_closedpath(
         bezier, inside_closedpath, tolerance=0.01):
     """
-    bezier : control points of the bezier segment
-    inside_closedpath : a function which returns true if the point is inside
-                        the path
+    Split a bezier curve into two at the intersection with a closed path.
+
+    Parameters
+    ----------
+    bezier : array-like(N, 2)
+        Control points of the bezier segment. See `.BezierSegment`.
+    inside_closedpath : callable
+        A function returning True if a given point (x, y) is inside the
+        closed path. See also `.find_bezier_t_intersecting_with_closedpath`.
+    tolerance : float
+        The tolerance for the intersection. See also
+        `.find_bezier_t_intersecting_with_closedpath`.
+
+    Returns
+    -------
+    left, right
+        Lists of control points for the two bezier segments.
     """
 
     bz = BezierSegment(bezier)
@@ -205,12 +240,18 @@ def find_r_to_boundary_of_closedpath(
     Find a radius r (centered at *xy*) between *rmin* and *rmax* at
     which it intersect with the path.
 
-    inside_closedpath : function
-    cx, cy : center
-    cos_t, sin_t : cosine and sine for the angle
-    rmin, rmax :
+    Parameters
+    ----------
+    inside_closedpath : callable
+        A function returning True if a given point (x, y) is inside the
+        closed path.
+    xy : float, float
+        The center of the radius.
+    cos_t, sin_t : float
+        Cosine and sine for the angle.
+    rmin, rmax : float
+        Starting parameters for the radius search.
     """
-
     cx, cy = xy
 
     def _f(r):
@@ -228,7 +269,6 @@ def split_path_inout(path, inside, tolerance=0.01, reorder_inout=False):
     Divide a path into two segments at the point where ``inside(x, y)`` becomes
     False.
     """
-
     path_iter = path.iter_segments()
 
     ctl_points, command = next(path_iter)
@@ -287,6 +327,14 @@ def split_path_inout(path, inside, tolerance=0.01, reorder_inout=False):
 
 
 def inside_circle(cx, cy, r):
+    """
+    Return a function that checks whether a point is in a circle with center
+    (*cx*, *cy*) and radius *r*.
+
+    The returned function has the signature::
+
+        f(xy: Tuple[float, float]) -> bool
+    """
     r2 = r ** 2
 
     def _f(xy):
@@ -309,8 +357,22 @@ def get_cos_sin(x0, y0, x1, y1):
 @cbook._rename_parameter("3.1", "tolerence", "tolerance")
 def check_if_parallel(dx1, dy1, dx2, dy2, tolerance=1.e-5):
     """
-    Return 1 if two lines are parallel in same direction, -1 if two lines are
-    parallel in opposite direction, 0 otherwise.
+    Check if two lines are parallel.
+
+    Parameters
+    ----------
+    dx1, dy1, dx2, dy2 : float
+        The gradients *dy*/*dx* of the two lines.
+    tolerance : float
+        The angular tolerange in rad up to which the lines are considered
+        parallel.
+
+    Returns
+    -------
+    is_parallel
+        - 1 if two lines are parallel in same direction.
+        - -1 if two lines are parallel in opposite direction.
+        - False otherwise.
     """
     theta1 = np.arctan2(dx1, dy1)
     theta2 = np.arctan2(dx2, dy2)