From f941277a9d57cecc92db29e439f5c9fe10bedfe1 Mon Sep 17 00:00:00 2001 From: Amaan Qureshi Date: Sun, 12 Jan 2025 13:44:23 -0500 Subject: [PATCH] docs(lib): improve documentation on `ts_tree_get_changed_ranges` and `ts_query_cursor_set_{byte,point}_range` --- lib/binding_rust/bindings.rs | 6 +++--- lib/include/tree_sitter/api.h | 25 +++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/lib/binding_rust/bindings.rs b/lib/binding_rust/bindings.rs index fb052f3d..ceffdc21 100644 --- a/lib/binding_rust/bindings.rs +++ b/lib/binding_rust/bindings.rs @@ -309,7 +309,7 @@ extern "C" { pub fn ts_tree_edit(self_: *mut TSTree, edit: *const TSInputEdit); } extern "C" { - #[doc = " Compare an old edited syntax tree to a new syntax tree representing the same\n document, returning an array of ranges whose syntactic structure has changed.\n\n For this to work correctly, the old syntax tree must have been edited such\n that its ranges match up to the new tree. Generally, you'll want to call\n this function right after calling one of the [`ts_parser_parse`] functions.\n You need to pass the old tree that was passed to parse, as well as the new\n tree that was returned from that function.\n\n The returned array is allocated using `malloc` and the caller is responsible\n for freeing it using `free`. The length of the array will be written to the\n given `length` pointer."] + #[doc = " Compare an old edited syntax tree to a new syntax tree representing the same\n document, returning an array of ranges whose syntactic structure has changed.\n\n For this to work correctly, the old syntax tree must have been edited such\n that its ranges match up to the new tree. Generally, you'll want to call\n this function right after calling one of the [`ts_parser_parse`] functions.\n You need to pass the old tree that was passed to parse, as well as the new\n tree that was returned from that function.\n\n The returned ranges indicate areas where the hierarchical structure of syntax\n nodes (from root to leaf) has changed between the old and new trees. Characters\n outside these ranges have identical ancestor nodes in both trees.\n\n Note that the returned ranges may be slightly larger than the exact changed areas,\n but Tree-sitter attempts to make them as small as possible.\n\n The returned array is allocated using `malloc` and the caller is responsible\n for freeing it using `free`. The length of the array will be written to the\n given `length` pointer."] pub fn ts_tree_get_changed_ranges( old_tree: *const TSTree, new_tree: *const TSTree, @@ -708,7 +708,7 @@ extern "C" { pub fn ts_query_cursor_timeout_micros(self_: *const TSQueryCursor) -> u64; } extern "C" { - #[doc = " Set the range of bytes in which the query will be executed.\n\n This will return `false` if the start byte is greater than the end byte, otherwise\n it will return `true`."] + #[doc = " Set the range of bytes in which the query will be executed.\n\n The query cursor will return matches that intersect with the given point range.\n This means that a match may be returned even if some of its captures fall\n outside the specified range, as long as at least part of the match\n overlaps with the range.\n\n For example, if a query pattern matches a node that spans a larger area\n than the specified range, but part of that node intersects with the range,\n the entire match will be returned.\n\n This will return `false` if the start byte is greater than the end byte, otherwise\n it will return `true`."] pub fn ts_query_cursor_set_byte_range( self_: *mut TSQueryCursor, start_byte: u32, @@ -716,7 +716,7 @@ extern "C" { ) -> bool; } extern "C" { - #[doc = " Set the range of (row, column) positions in which the query will be executed.\n\n This will return `false` if the start point is greater than the end point, otherwise\n it will return `true`."] + #[doc = " Set the range of (row, column) positions in which the query will be executed.\n\n The query cursor will return matches that intersect with the given point range.\n This means that a match may be returned even if some of its captures fall\n outside the specified range, as long as at least part of the match\n overlaps with the range.\n\n For example, if a query pattern matches a node that spans a larger area\n than the specified range, but part of that node intersects with the range,\n the entire match will be returned.\n\n This will return `false` if the start point is greater than the end point, otherwise\n it will return `true`."] pub fn ts_query_cursor_set_point_range( self_: *mut TSQueryCursor, start_point: TSPoint, diff --git a/lib/include/tree_sitter/api.h b/lib/include/tree_sitter/api.h index 29a55f56..cb34d1fc 100644 --- a/lib/include/tree_sitter/api.h +++ b/lib/include/tree_sitter/api.h @@ -477,6 +477,13 @@ void ts_tree_edit(TSTree *self, const TSInputEdit *edit); * You need to pass the old tree that was passed to parse, as well as the new * tree that was returned from that function. * + * The returned ranges indicate areas where the hierarchical structure of syntax + * nodes (from root to leaf) has changed between the old and new trees. Characters + * outside these ranges have identical ancestor nodes in both trees. + * + * Note that the returned ranges may be slightly larger than the exact changed areas, + * but Tree-sitter attempts to make them as small as possible. + * * The returned array is allocated using `malloc` and the caller is responsible * for freeing it using `free`. The length of the array will be written to the * given `length` pointer. @@ -1102,6 +1109,15 @@ uint64_t ts_query_cursor_timeout_micros(const TSQueryCursor *self); /** * Set the range of bytes in which the query will be executed. * + * The query cursor will return matches that intersect with the given point range. + * This means that a match may be returned even if some of its captures fall + * outside the specified range, as long as at least part of the match + * overlaps with the range. + * + * For example, if a query pattern matches a node that spans a larger area + * than the specified range, but part of that node intersects with the range, + * the entire match will be returned. + * * This will return `false` if the start byte is greater than the end byte, otherwise * it will return `true`. */ @@ -1110,6 +1126,15 @@ bool ts_query_cursor_set_byte_range(TSQueryCursor *self, uint32_t start_byte, ui /** * Set the range of (row, column) positions in which the query will be executed. * + * The query cursor will return matches that intersect with the given point range. + * This means that a match may be returned even if some of its captures fall + * outside the specified range, as long as at least part of the match + * overlaps with the range. + * + * For example, if a query pattern matches a node that spans a larger area + * than the specified range, but part of that node intersects with the range, + * the entire match will be returned. + * * This will return `false` if the start point is greater than the end point, otherwise * it will return `true`. */