add docstrings (#11)

leo-collins · web-flow · commit 46bc7d2ed41b · 2026-03-25T20:26:07.000Z
diff --git a/rtree-capi/include/rtree-capi.h b/rtree-capi/include/rtree-capi.h
@@ -17,38 +17,88 @@ typedef struct RTreeH RTreeH;
 
 typedef struct RTreeNodeH RTreeNodeH;
 
+/**
+ * Returns a new tree containing the given objects. The input arrays must have the same length.
+ * Returns an empty tree if the input arrays are empty.
+ * Supported dimensions are currently 1, 2, and 3. Returns an InvalidDimension error for unsupported dimensions.
+ * You must free the returned tree with `rtree_free`.
+ */
 RTreeError rtree_bulk_load(struct RTreeH **tree,
                            const double *mins,
                            const double *maxs,
                            const size_t *ids,
                            size_t n,
                            uint32_t dim);
 
+/**
+ * Returns a new empty tree with the given dimension.
+ */
 RTreeError rtree_create(struct RTreeH **tree, uint32_t dim);
 
-RTreeError rtree_depth(const struct RTreeH *tree, size_t *depth_out);
+/**
+ * Returns the depth of the tree, defined as the number of edges in the longest path from the root to a leaf.
+ * An empty tree has depth 0.
+ */
+RTreeError rtree_depth(const struct RTreeH *tree,
+                       size_t *depth_out);
 
+/**
+ * Frees the given tree.
+ */
 RTreeError rtree_free(struct RTreeH *tree);
 
+/**
+ * Frees the ids returned by `rtree_locate_all_at_point`.
+ */
 RTreeError rtree_free_ids(size_t *ids, size_t n);
 
+/**
+ * Returns the dimension of the tree.
+ */
 RTreeError rtree_get_dimension(const struct RTreeH *tree, uint32_t *dim);
 
+/**
+ * Returns the ids of all objects in the tree that contain the given point.
+ * If no objects contain the point, returns nids_out = 0.
+ * You must free the returned ids with `rtree_free_ids`.
+ */
 RTreeError rtree_locate_all_at_point(const struct RTreeH *tree,
                                      const double *point,
                                      size_t **ids_out,
                                      size_t *nids_out);
 
+/**
+ * Returns the child nodes of a given node. You must free the returned child nodes with `rtree_node_children_free`.
+ * If the node is a leaf, or a root node of an empty tree, returns nchildren = 0.
+ */
 RTreeError rtree_node_children(const struct RTreeNodeH *node,
                                struct RTreeNodeH ***children,
                                size_t *nchildren);
 
+/**
+ * Frees the child nodes returned by `rtree_node_children`.
+ */
 RTreeError rtree_node_children_free(struct RTreeNodeH **children, size_t n);
 
+/**
+ * Returns the minimum bounding box that covers all the boxes in the node.
+ * Returns an EmptyNodeEnvelope error if given a root node of an empty tree, which has no envelope.
+ */
 RTreeError rtree_node_envelope(const struct RTreeNodeH *node, double *min_out, double *max_out);
 
+/**
+ * Frees the node returned by `rtree_root_node`.
+ */
 RTreeError rtree_node_free(struct RTreeNodeH *node);
 
+/**
+ * Returns the root node of a tree. You must free the returned node with `rtree_node_free`.
+ * If the tree is empty, returns an EmptyNode.
+ */
 RTreeError rtree_root_node(const struct RTreeH *tree, struct RTreeNodeH **node);
 
+/**
+ * Returns the size of the tree, defined as the number of objects in the tree.
+ * An empty tree has size 0.
+ */
 RTreeError rtree_size(const struct RTreeH *tree, size_t *size_out);
diff --git a/rtree-capi/src/node.rs b/rtree-capi/src/node.rs
@@ -15,6 +15,8 @@ enum NodeRef {
 
 pub enum RTreeNodeH {}
 
+/// Returns the root node of a tree. You must free the returned node with `rtree_node_free`.
+/// If the tree is empty, returns an EmptyNode.
 #[no_mangle]
 pub extern "C" fn rtree_root_node(tree: *const RTreeH, node: *mut *mut RTreeNodeH) -> RTreeError {
     if tree.is_null() || node.is_null() {
@@ -40,6 +42,8 @@ pub extern "C" fn rtree_root_node(tree: *const RTreeH, node: *mut *mut RTreeNode
     RTreeError::Success
 }
 
+/// Returns the child nodes of a given node. You must free the returned child nodes with `rtree_node_children_free`.
+/// If the node is a leaf, or a root node of an empty tree, returns nchildren = 0.
 #[no_mangle]
 pub extern "C" fn rtree_node_children(
     node: *const RTreeNodeH,
@@ -115,6 +119,8 @@ fn write_aabb<const DIM: usize>(aabb: AABB<[f64; DIM]>, min_out: *mut f64, max_o
     }
 }
 
+/// Returns the minimum bounding box that covers all the boxes in the node.
+/// Returns an EmptyNodeEnvelope error if given a root node of an empty tree, which has no envelope.
 #[no_mangle]
 pub extern "C" fn rtree_node_envelope(
     node: *const RTreeNodeH,
@@ -146,6 +152,7 @@ pub extern "C" fn rtree_node_envelope(
     RTreeError::Success
 }
 
+/// Frees the node returned by `rtree_root_node`.
 #[no_mangle]
 pub extern "C" fn rtree_node_free(node: *mut RTreeNodeH) -> RTreeError {
     if node.is_null() {
@@ -155,6 +162,7 @@ pub extern "C" fn rtree_node_free(node: *mut RTreeNodeH) -> RTreeError {
     RTreeError::Success
 }
 
+/// Frees the child nodes returned by `rtree_node_children`.
 #[no_mangle]
 pub extern "C" fn rtree_node_children_free(children: *mut *mut RTreeNodeH, n: usize) -> RTreeError {
     if children.is_null() {
diff --git a/rtree-capi/src/rtree.rs b/rtree-capi/src/rtree.rs
@@ -16,6 +16,7 @@ pub enum RTreeDim {
 // Opaque handle for C api
 pub enum RTreeH {}
 
+/// Returns a new empty tree with the given dimension.
 #[no_mangle]
 pub extern "C" fn rtree_create(tree: *mut *mut RTreeH, dim: u32) -> RTreeError {
     if tree.is_null() {
@@ -31,6 +32,7 @@ pub extern "C" fn rtree_create(tree: *mut *mut RTreeH, dim: u32) -> RTreeError {
     RTreeError::Success
 }
 
+/// Frees the given tree.
 #[no_mangle]
 pub extern "C" fn rtree_free(tree: *mut RTreeH) -> RTreeError {
     if tree.is_null() {
@@ -48,6 +50,7 @@ fn _rtree_get_dimension(tree: &RTreeDim) -> u32 {
     }
 }
 
+/// Returns the dimension of the tree.
 #[no_mangle]
 pub extern "C" fn rtree_get_dimension(tree: *const RTreeH, dim: *mut u32) -> RTreeError {
     if tree.is_null() || dim.is_null() {
@@ -92,6 +95,10 @@ fn _interval_tree_bulk_load(
     IntervalTree::bulk_load(mins, maxs, data)
 }
 
+/// Returns a new tree containing the given objects. The input arrays must have the same length.
+/// Returns an empty tree if the input arrays are empty.
+/// Supported dimensions are currently 1, 2, and 3. Returns an InvalidDimension error for unsupported dimensions.
+/// You must free the returned tree with `rtree_free`.
 #[no_mangle]
 pub extern "C" fn rtree_bulk_load(
     tree: *mut *mut RTreeH,
@@ -131,6 +138,9 @@ pub extern "C" fn rtree_bulk_load(
     RTreeError::Success
 }
 
+/// Returns the ids of all objects in the tree that contain the given point.
+/// If no objects contain the point, returns nids_out = 0.
+/// You must free the returned ids with `rtree_free_ids`.
 #[no_mangle]
 pub extern "C" fn rtree_locate_all_at_point(
     tree: *const RTreeH,
@@ -168,6 +178,8 @@ pub extern "C" fn rtree_locate_all_at_point(
     RTreeError::Success
 }
 
+/// Returns the size of the tree, defined as the number of objects in the tree.
+/// An empty tree has size 0.
 #[no_mangle]
 pub extern "C" fn rtree_size(tree: *const RTreeH, size_out: *mut usize) -> RTreeError {
     if tree.is_null() || size_out.is_null() {
@@ -207,6 +219,8 @@ fn _rtree_depth<T: RTreeObject>(node: &ParentNode<T>) -> usize {
         .unwrap_or(0)
 }
 
+/// Returns the depth of the tree, defined as the number of edges in the longest path from the root to a leaf.
+/// An empty tree has depth 0.
 #[no_mangle]
 pub extern "C" fn rtree_depth(tree: *const RTreeH, depth_out: *mut usize) -> RTreeError {
     if tree.is_null() || depth_out.is_null() {
@@ -231,6 +245,7 @@ pub extern "C" fn rtree_depth(tree: *const RTreeH, depth_out: *mut usize) -> RTr
     RTreeError::Success
 }
 
+/// Frees the ids returned by `rtree_locate_all_at_point`.
 #[no_mangle]
 pub extern "C" fn rtree_free_ids(ids: *mut usize, n: usize) -> RTreeError {
     if ids.is_null() {
