neovim

commit 6c150e0b9312ece13f13b7ff2e9743592bc9d431
parent d3e9cbedc700a5ae9f64fdced07cdddbb4ef13d1
Author: L Lllvvuu <git@llllvvuu.dev>
Date:   Wed, 27 Sep 2023 02:51:42 -0700

docs(treesitter): add disclaimer about needing to parse before `get_node()`

Problem:
---
Misuse of `get_node()` is common:
https://github.com/search?q=get_node_at_cursor+language%3Alua&type=code

Solution:
---
Add a note clarifying proper usage.

Diffstat:
M
runtime/doc/treesitter.txt
 | 
6
++++++
M
runtime/lua/vim/treesitter.lua
 | 
8
++++++++

2 files changed, 14 insertions(+), 0 deletions(-)
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
@@ -599,6 +599,12 @@ get_captures_at_pos({bufnr}, {row}, {col})
 get_node({opts})                                   *vim.treesitter.get_node()*
     Returns the smallest named node at the given position
 
+    NOTE: Calling this on an unparsed tree can yield an invalid node. If the
+    tree is not known to be parsed by, e.g., an active highlighter, parse the
+    tree first via >lua
+        vim.treesitter.get_parser(bufnr):parse(range)
+<
+
     Parameters: ~
       • {opts}  (table|nil) Optional keyword arguments:
                 • bufnr integer|nil Buffer number (nil or 0 for current
diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua
@@ -350,6 +350,14 @@ end
 
 --- Returns the smallest named node at the given position
 ---
+--- NOTE: Calling this on an unparsed tree can yield an invalid node.
+--- If the tree is not known to be parsed by, e.g., an active highlighter,
+--- parse the tree first via
+---
+--- ```lua
+--- vim.treesitter.get_parser(bufnr):parse(range)
+--- ```
+---
 ---@param opts table|nil Optional keyword arguments:
 ---             - bufnr integer|nil Buffer number (nil or 0 for current buffer)
 ---             - pos table|nil 0-indexed (row, col) tuple. Defaults to cursor position in the