From 69f075b9044630582376d46866497c446205fe32 Mon Sep 17 00:00:00 2001
From: Freddie Witherden <freddie@witherden.org>
Date: Mon, 3 Mar 2025 17:26:28 -0600
Subject: [PATCH] Document bulk interfaces (#346)

---
 docs/source/performance.rst |  3 ++-
 rtree/index.py              | 40 +++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/docs/source/performance.rst b/docs/source/performance.rst
index 6c2d50d0..79d4db1c 100644
--- a/docs/source/performance.rst
+++ b/docs/source/performance.rst
@@ -80,4 +80,5 @@ Use the correct query method
 
 Use :py:meth:`~rtree.index.Index.count` if you only need a count and
 :py:meth:`~rtree.index.Index.intersection` if you only need the ids.
-Otherwise, lots of data may potentially be copied.
+Otherwise, lots of data may potentially be copied.  If possible also
+make use of the bulk query methods suffixed with `_v`.
diff --git a/rtree/index.py b/rtree/index.py
index bf4d6ac2..3c765530 100644
--- a/rtree/index.py
+++ b/rtree/index.py
@@ -1047,6 +1047,18 @@ def nearest(
         return self._get_ids(it, p_num_results.contents.value)
 
     def intersection_v(self, mins, maxs):
+        """Bulk intersection query for obtaining the ids of entries
+        which intersect with the provided bounding boxes.  The return
+        value is a tuple consisting of two 1D NumPy arrays: one of
+        intersecting ids and another containing the counts for each
+        bounding box.
+
+        :param mins: A NumPy array of shape `(n, d)` containing the
+            minima to query.
+
+        :param maxs: A NumPy array of shape `(n, d)` containing the
+            maxima to query.
+        """
         import numpy as np
 
         assert mins.shape == maxs.shape
@@ -1102,6 +1114,34 @@ def nearest_v(
         strict=False,
         return_max_dists=False,
     ):
+        """Bulk ``k``-nearest query for the given bounding boxes.  The
+        return value is a tuple consisting of, by default, two 1D NumPy
+        arrays: one of intersecting ids and another containing the
+        counts for each bounding box.
+
+        :param mins: A NumPy array of shape `(n, d)` containing the
+            minima to query.
+
+        :param maxs: A NumPy array of shape `(n, d)` containing the
+            maxima to query.
+
+        :param num_results: The maximum number of neighbors to return
+            for each bounding box.  If there are multiple equidistant
+            furthest neighbors then, by default, they are *all*
+            returned.  Hence, the actual number of results can be
+            greater than requested.
+
+        :param max_dists: Optional; a NumPy array of shape `(n,)`
+            containing the maximum distance to consider for each
+            bounding box.
+
+        :param strict: If True then each point will never return more
+            than `num_results` even in cases of equidistant furthest
+            neighbors.
+
+        :param return_max_dists: If True, the distance of the furthest
+            neighbor for each bounding box will also be returned.
+        """
         import numpy as np
 
         assert mins.shape == maxs.shape