update quadtree_point_in_polygon and quadtree_point_to_nearest_linest…

…ring docstrings (fixes #733)

cpp/include/cuspatial/spatial_join.hpp

@@ -32,9 +32,11 @@ namespace cuspatial {
 /**
  * @brief Search a quadtree for polygon or linestring bounding box intersections.
  *
- * @note `scale` is applied to (x - x_min) and (y - y_min) to convert coordinates into a Morton code
- * in 2D space.
- * @note `max_depth` should be less than 16, since Morton codes are represented as `uint32_t`.
+ * @note 2D coordinates are converted into a 1D Morton code by dividing each x/y by the `scale`:
+ * (`(x - min_x) / scale` and `(y - min_y) / scale`).
+ * @note `max_depth` should be less than 16, since Morton codes are represented as `uint32_t`. The
+ * eventual number of levels may be less than `max_depth` if the number of points is small or
+ * `max_size` is large.
  *
  * @param quadtree: cudf table representing a quadtree (key, level, is_quad, length, offset).
  * @param bbox: cudf table of bounding boxes as four columns (x_min, y_min, x_max, y_max).
@@ -104,8 +106,8 @@ std::unique_ptr<cudf::table> join_quadtree_and_bounding_boxes(
  * polygon_offset - UINT32 column of polygon indices
  *   point_offset - UINT32 column of point indices
  *
- * @note The returned polygon and point indices are offsets into the poly_quad_pairs inputs and
- * (point_x, point_y), respectively.
+ * @note The returned polygon and point indices are offsets into the `poly_quad_pairs` inputs and
+ * `point_indices`, respectively.
  *
  **/
 std::unique_ptr<cudf::table> quadtree_point_in_polygon(
@@ -153,8 +155,8 @@ std::unique_ptr<cudf::table> quadtree_point_in_polygon(
  *   distance          - FLOAT or DOUBLE column (based on input point data type) of distances
  *                       between each point and linestring
  *
- * @note The returned point and linestring indices are offsets into the (point_x, point_y) and
- * linestring_quad_pairs inputs, respectively.
+ * @note The returned point and linestring indices are offsets into the `point_indices` and
+ * `linestring_quad_pairs` inputs, respectively.
  *
  **/
 std::unique_ptr<cudf::table> quadtree_point_to_nearest_linestring(

python/cuspatial/cuspatial/core/spatial/join.py

@@ -66,12 +66,13 @@ def point_in_polygon(
     # Point 1: (-8, -8) falls in the first polygon
     # Point 2: (6.0, 6.0) falls in the second polygon
 
-    note
-    input Series x and y will not be index aligned, but computed as
+    Notes
+    -----
+
+    * input Series x and y will not be index aligned, but computed as
     sequential arrays.
 
-    note
-    poly_ring_offsets must contain only the rings that make up the polygons
+    * poly_ring_offsets must contain only the rings that make up the polygons
     indexed by poly_offsets. If there are rings in poly_ring_offsets that
     are not part of the polygons in poly_offsets, results are likely to be
     incorrect and behavior is undefined.
@@ -238,7 +239,8 @@ def quadtree_point_in_polygon(
         polygon_index : cudf.Series
             Indices of each polygon with which a point intersected.
         point_index : cudf.Series
-            Indices of each point that intersects with a polygon.
+            Indices of each point (in ``point_indices``) that intersects with a
+            polygon.
     """
 
     (
@@ -311,7 +313,8 @@ def quadtree_point_to_nearest_linestring(
         between the two.
 
         point_index : cudf.Series
-            Indices of each point that intersects with a linestring.
+            Indices of each point (in ``point_indices``) that intersects with
+            a linestring.
         linestring_index : cudf.Series
             Indices of each linestring with which a point intersected.
         distance : cudf.Series