Document perf characteristic of to_node

1 files changed, 9 insertions, 0 deletions

diff --git a/crates/syntax/src/ptr.rs b/crates/syntax/src/ptr.rs
index 195d2251b..c077a04cb 100644
--- a/crates/syntax/src/ptr.rs
+++ b/crates/syntax/src/ptr.rs
@@ -32,6 +32,15 @@ impl SyntaxNodePtr {
         SyntaxNodePtr { range: node.text_range(), kind: node.kind() }
     }
 
+    /// "Dereference" the pointer to get the node it points to.
+    ///
+    /// Panics if node is not found, so make sure that `root` syntax tree is
+    /// equivalent (is build from the same text) to the tree which was
+    /// originally used to get this [`SyntaxNodePtr`].
+    ///
+    /// The complexity is linear in the depth of the tree and logarithmic in
+    /// tree width. As most trees are shallow, thinking about this as
+    /// `O(log(N))` in the size of the tree is not too wrong!
     pub fn to_node(&self, root: &SyntaxNode) -> SyntaxNode {
         assert!(root.parent().is_none());
         successors(Some(root.clone()), |node| {