From 75e57a06a7a097ce8cb208c1a0db0b836df40538 Mon Sep 17 00:00:00 2001
From: Davis Vaughan <davis@posit.co>
Date: Mon, 17 Jun 2024 20:47:10 -0400
Subject: [PATCH] Document `tree_root_node_with_offset()`

---
 R/tree.R                          | 54 +++++++++++++++++++++++++-
 man/tree_root_node_with_offset.Rd | 64 +++++++++++++++++++++++++++++++
 2 files changed, 116 insertions(+), 2 deletions(-)
 create mode 100644 man/tree_root_node_with_offset.Rd

diff --git a/R/tree.R b/R/tree.R
index fdf7d67..620ba86 100644
--- a/R/tree.R
+++ b/R/tree.R
@@ -34,9 +34,59 @@ tree_root_node <- function(x) {
   new_node(raw, x)
 }
 
-# TODO: When documenting, pull from this PR to talk about potential use cases
-# for this https://github.com/tree-sitter/tree-sitter/pull/1845
+#' Retrieve an offset root node
+#'
+#' @description
+#' `tree_root_node_with_offset()` is similar to [tree_root_node()],
+#' but the returned root node's position has been shifted by the given number of
+#' bytes, rows, and columns.
+#'
+#' This function allows you to parse a subset of a document with
+#' [parser_parse()] as if it were a self-contained document, but then later
+#' access the syntax tree in the coordinate space of the larger document.
+#'
+#' Note that the underlying `text` within `x` is not what you are offsetting
+#' into. Instead, you should assume that the `text` you provided to
+#' [parser_parse()] already contained the entire subset of the document you care
+#' about, and the offset you are providing is how far into the document the
+#' beginning of `text` is.
+#'
+#' @inheritParams x_tree_sitter_tree
+#'
+#' @param byte,point `[double(1), tree_sitter_point]`
+#'
+#'   A byte and point offset combination.
+#'
+#' @returns
+#' An offset root node.
+#'
 #' @export
+#' @examplesIf treesitter:::has_r_grammar()
+#' language <- treesitter.r::language()
+#' parser <- parser(language)
+#'
+#' text <- "fn <- function() { 1 + 1 }"
+#' tree <- parser_parse(parser, text)
+#'
+#' # If `text` was the whole document, you can just use `tree_root_node()`
+#' node <- tree_root_node(tree)
+#'
+#' # If `text` represents a subset of the document, use
+#' # `tree_root_node_with_offset()` to be able to get positions in the
+#' # coordinate space of the original document.
+#' byte <- 5
+#' point <- point(5, 0)
+#' node_offset <- tree_root_node_with_offset(tree, byte, point)
+#'
+#' # The position of `fn` if you treat `text` as the whole document
+#' node |>
+#'   node_child(1) |>
+#'   node_child(1)
+#'
+#' # The position of `fn` if you treat `text` as a subset of a larger document
+#' node_offset |>
+#'   node_child(1) |>
+#'   node_child(1)
 tree_root_node_with_offset <- function(x, byte, point) {
   check_tree(x)
   check_point(point)
diff --git a/man/tree_root_node_with_offset.Rd b/man/tree_root_node_with_offset.Rd
new file mode 100644
index 0000000..4872dca
--- /dev/null
+++ b/man/tree_root_node_with_offset.Rd
@@ -0,0 +1,64 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/tree.R
+\name{tree_root_node_with_offset}
+\alias{tree_root_node_with_offset}
+\title{Retrieve an offset root node}
+\usage{
+tree_root_node_with_offset(x, byte, point)
+}
+\arguments{
+\item{x}{\verb{[tree_sitter_tree]}
+
+A tree.}
+
+\item{byte, point}{\verb{[double(1), tree_sitter_point]}
+
+A byte and point offset combination.}
+}
+\value{
+An offset root node.
+}
+\description{
+\code{tree_root_node_with_offset()} is similar to \code{\link[=tree_root_node]{tree_root_node()}},
+but the returned root node's position has been shifted by the given number of
+bytes, rows, and columns.
+
+This function allows you to parse a subset of a document with
+\code{\link[=parser_parse]{parser_parse()}} as if it were a self-contained document, but then later
+access the syntax tree in the coordinate space of the larger document.
+
+Note that the underlying \code{text} within \code{x} is not what you are offsetting
+into. Instead, you should assume that the \code{text} you provided to
+\code{\link[=parser_parse]{parser_parse()}} already contained the entire subset of the document you care
+about, and the offset you are providing is how far into the document the
+beginning of \code{text} is.
+}
+\examples{
+\dontshow{if (treesitter:::has_r_grammar()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+language <- treesitter.r::language()
+parser <- parser(language)
+
+text <- "fn <- function() { 1 + 1 }"
+tree <- parser_parse(parser, text)
+
+# If `text` was the whole document, you can just use `tree_root_node()`
+node <- tree_root_node(tree)
+
+# If `text` represents a subset of the document, use
+# `tree_root_node_with_offset()` to be able to get positions in the
+# coordinate space of the original document.
+byte <- 5
+point <- point(5, 0)
+node_offset <- tree_root_node_with_offset(tree, byte, point)
+
+# The position of `fn` if you treat `text` as the whole document
+node |>
+  node_child(1) |>
+  node_child(1)
+
+# The position of `fn` if you treat `text` as a subset of a larger document
+node_offset |>
+  node_child(1) |>
+  node_child(1)
+\dontshow{\}) # examplesIf}
+}