Improved documentation

Author: ianthomas23

lib/matplotlib/contour.py

@@ -1037,6 +1037,16 @@ def _get_lowers_and_uppers(self):
         return (lowers, uppers)
 
     def _make_paths(self, segs, kinds):
+        """
+        Create and return Path objects for the specified segments and optional
+        kind codes.  segs is a list of numpy arrays, each array is either a
+        closed line loop or open line strip of 2D points with a shape of
+        (npoints, 2).  kinds is either None or a list (with the same length as
+        segs) of numpy arrays, each array is of shape (npoints,) and contains
+        the kinds codes for the corresponding line in segs.  If kinds is None
+        then the Path constructor creates the kind codes assuming that the line
+        is an open strip.
+        """
         if kinds is None:
             return [mpath.Path(seg) for seg in segs]
         else:

src/_contour.cpp

@@ -386,10 +386,21 @@ void QuadContourGenerator::append_contour_line_to_vertices_and_codes(
     PyObject* vertices_list,
     PyObject* codes_list) const
 {
+    // Convert ContourLine to Python equivalent, and clear it for reuse.
+    // This function is called once for each line generated in create_contour().
+    // A line is either a closed line loop (in which case the last point is
+    // identical to the first) or an open line strip.  Two NumPy arrays are
+    // created for each line:
+    //   vertices is a double array of shape (npoints, 2) containing the (x, y)
+    //     coordinates of the points in the line
+    //   codes is a uint8 array of shape (npoints,) containing the 'kind codes'
+    //     which are defined in the Path class
+    // and they are appended to the Python lists vertices_list and codes_list
+    // respectively for return to the Python calling function.
+
     assert(vertices_list != 0 && "Null python vertices_list");
     assert(codes_list != 0 && "Null python codes_list");
 
-    // Convert ContourLine to python equivalent, and clear it.
     npy_intp npoints = static_cast<npy_intp>(contour_line.size());
 
     npy_intp vertices_dims[2] = {npoints, 2};
@@ -407,6 +418,7 @@ void QuadContourGenerator::append_contour_line_to_vertices_and_codes(
         *codes_ptr++ = (point == contour_line.begin() ? MOVETO : LINETO);
     }
 
+    // Closed line loop has identical first and last (x, y) points.
     if (contour_line.size() > 1 && contour_line.front() == contour_line.back())
         *(codes_ptr-1) = CLOSEPOLY;
 
@@ -425,6 +437,18 @@ void QuadContourGenerator::append_contour_to_vertices_and_codes(
     PyObject* vertices_list,
     PyObject* codes_list) const
 {
+    // Convert Contour to Python equivalent, and clear it for reuse.
+    // This function is called once for each polygon generated in
+    // create_filled_contour().  A polygon consists of an outer line loop
+    // (called the parent) and zero or more inner line loops or holes (called
+    // the children).  Two NumPy arrays are created for each polygon:
+    //   vertices is a double array of shape (npoints, 2) containing the (x, y)
+    //     coordinates of the points in the polygon (parent plus children)
+    //   codes is a uint8 array of shape (npoints,) containing the 'kind codes'
+    //     which are defined in the Path class
+    // and they are appended to the Python lists vertices_list and codes_list
+    // respectively for return to the Python calling function.
+
     assert(vertices_list != 0 && "Null python vertices_list");
     assert(codes_list != 0 && "Null python codes_list");
 

src/tri/_tri.cpp

@@ -602,6 +602,18 @@ void TriContourGenerator::clear_visited_flags(bool include_boundaries)
 
 PyObject* TriContourGenerator::contour_line_to_segs_and_kinds(const Contour& contour)
 {
+    // Convert all of the lines generated by a call to create_contour() into
+    // their Python equivalents for return to the calling function.
+    // A line is either a closed line loop (in which case the last point is
+    // identical to the first) or an open line strip.  Two NumPy arrays are
+    // created for each line:
+    //   vertices is a double array of shape (npoints, 2) containing the (x, y)
+    //     coordinates of the points in the line
+    //   codes is a uint8 array of shape (npoints,) containing the 'kind codes'
+    //     which are defined in the Path class
+    // and they are appended to the Python lists vertices_list and codes_list
+    // respectively for return to the Python calling function.
+
     PyObject* vertices_list = PyList_New(contour.size());
     if (vertices_list == 0)
         throw std::runtime_error("Failed to create Python list");
@@ -633,6 +645,7 @@ PyObject* TriContourGenerator::contour_line_to_segs_and_kinds(const Contour& con
             *codes_ptr++ = (it == contour_line.begin() ? MOVETO : LINETO);
         }
 
+        // Closed line loop has identical first and last (x, y) points.
         if (contour_line.size() > 1 &&
             contour_line.front() == contour_line.back())
             *(codes_ptr-1) = CLOSEPOLY;
@@ -660,6 +673,20 @@ PyObject* TriContourGenerator::contour_line_to_segs_and_kinds(const Contour& con
 
 PyObject* TriContourGenerator::contour_to_segs_and_kinds(const Contour& contour)
 {
+    // Convert all of the polygons generated by a call to
+    // create_filled_contour() into their Python equivalents for return to the
+    // calling function.  All of the polygons' points and kinds codes are
+    // combined into single NumPy arrays for each; this avoids having
+    // to determine which polygons are holes as this will be determined by the
+    // renderer.  If there are ntotal points in all of the polygons, the two
+    // NumPy arrays created are:
+    //   vertices is a double array of shape (ntotal, 2) containing the (x, y)
+    //     coordinates of the points in the polygons
+    //   codes is a uint8 array of shape (ntotal,) containing the 'kind codes'
+    //     which are defined in the Path class
+    // and they are returned in the Python lists vertices_list and codes_list
+    // respectively.
+
     Contour::const_iterator line;
     ContourLine::const_iterator point;