docs(treesitter): generate inline docs for Ranges

docs(treesitter): in-place parameter description

docs(treesitter): remove internal type names

docs(treesitter): add missing private annotation

runtime/doc/treesitter.txt

@@ -358,7 +358,8 @@ The following directives are built in:
 <
     `offset!`                                      *treesitter-directive-offset!*
         Takes the range of the captured node and applies an offset. This will
-        set a new `Range4` object for the captured node with `capture_id` as
+        set a new range in the form of a list like { {start_row}, {start_col},
+        {end_row}, {end_col} } for the captured node with `capture_id` as
         `metadata[capture_id].range`. Useful for |treesitter-language-injections|.
 
         Parameters: ~
@@ -833,7 +834,13 @@ get_range({node}, {source}, {metadata})           *vim.treesitter.get_range()*
       • {metadata}  (`vim.treesitter.query.TSMetadata?`)
 
     Return: ~
-        (`Range6`)
+        (`table`) A table with the following fields:
+        • {[1]} (`integer`) start row
+        • {[2]} (`integer`) start column
+        • {[3]} (`integer`) start bytes
+        • {[4]} (`integer`) end row
+        • {[5]} (`integer`) end column
+        • {[6]} (`integer`) end bytes
 
                                           *vim.treesitter.get_string_parser()*
 get_string_parser({str}, {lang}, {opts})
@@ -1300,7 +1307,11 @@ LanguageTree:contains({range})                       *LanguageTree:contains()*
     Determines whether {range} is contained in the |LanguageTree|.
 
     Parameters: ~
-      • {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`
+      • {range}  (`table`) A table with the following fields:
+                 • {[1]} (`integer`) start row
+                 • {[2]} (`integer`) start column
+                 • {[3]} (`integer`) end row
+                 • {[4]} (`integer`) end column
 
     Return: ~
         (`boolean`)
@@ -1324,7 +1335,9 @@ LanguageTree:for_each_tree({fn})                *LanguageTree:for_each_tree()*
 LanguageTree:included_regions()              *LanguageTree:included_regions()*
     Gets the set of included regions managed by this LanguageTree. This can be
     different from the regions set by injection query, because a partial
-    |LanguageTree:parse()| drops the regions outside the requested range.
+    |LanguageTree:parse()| drops the regions outside the requested range. Each
+    list represents a range in the form of { {start_row}, {start_col},
+    {start_bytes}, {end_row}, {end_col}, {end_bytes} }.
 
     Return: ~
         (`table<integer, Range6[]>`)
@@ -1359,7 +1372,11 @@ LanguageTree:language_for_range({range})
     Gets the appropriate language that contains {range}.
 
     Parameters: ~
-      • {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`
+      • {range}  (`table`) A table with the following fields:
+                 • {[1]} (`integer`) start row
+                 • {[2]} (`integer`) start column
+                 • {[3]} (`integer`) end row
+                 • {[4]} (`integer`) end column
 
     Return: ~
         (`vim.treesitter.LanguageTree`) tree Managing {range}
@@ -1369,7 +1386,11 @@ LanguageTree:named_node_for_range({range}, {opts})
     Gets the smallest named node that contains {range}.
 
     Parameters: ~
-      • {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`
+      • {range}  (`table`) A table with the following fields:
+                 • {[1]} (`integer`) start row
+                 • {[2]} (`integer`) start column
+                 • {[3]} (`integer`) end row
+                 • {[4]} (`integer`) end column
       • {opts}   (`table?`) A table with the following fields:
                  • {ignore_injections}? (`boolean`, default: `true`) Ignore
                    injected languages
@@ -1382,7 +1403,11 @@ LanguageTree:node_for_range({range}, {opts})
     Gets the smallest node that contains {range}.
 
     Parameters: ~
-      • {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`
+      • {range}  (`table`) A table with the following fields:
+                 • {[1]} (`integer`) start row
+                 • {[2]} (`integer`) start column
+                 • {[3]} (`integer`) end row
+                 • {[4]} (`integer`) end column
       • {opts}   (`table?`) A table with the following fields:
                  • {ignore_injections}? (`boolean`, default: `true`) Ignore
                    injected languages
@@ -1443,7 +1468,11 @@ LanguageTree:tree_for_range({range}, {opts})
     Gets the tree that contains {range}.
 
     Parameters: ~
-      • {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`
+      • {range}  (`table`) A table with the following fields:
+                 • {[1]} (`integer`) start row
+                 • {[2]} (`integer`) start column
+                 • {[3]} (`integer`) end row
+                 • {[4]} (`integer`) end column
       • {opts}   (`table?`) A table with the following fields:
                  • {ignore_injections}? (`boolean`, default: `true`) Ignore
                    injected languages

runtime/lua/vim/treesitter/_range.lua

@@ -3,16 +3,19 @@ local api = vim.api
 local M = {}
 
 ---@class Range2
+---@inlinedoc
 ---@field [1] integer start row
 ---@field [2] integer end row
 
 ---@class Range4
+---@inlinedoc
 ---@field [1] integer start row
 ---@field [2] integer start column
 ---@field [3] integer end row
 ---@field [4] integer end column
 
 ---@class Range6
+---@inlinedoc
 ---@field [1] integer start row
 ---@field [2] integer start column
 ---@field [3] integer start bytes
@@ -150,6 +153,7 @@ function M.contains(r1, r2)
   return true
 end
 
+--- @private
 --- @param source integer|string
 --- @param index integer
 --- @return integer

runtime/lua/vim/treesitter/languagetree.lua

@@ -638,6 +638,8 @@ end
 ---Gets the set of included regions managed by this LanguageTree. This can be different from the
 ---regions set by injection query, because a partial |LanguageTree:parse()| drops the regions
 ---outside the requested range.
+---Each list represents a range in the form of
+---{ {start_row}, {start_col}, {start_bytes}, {end_row}, {end_col}, {end_bytes} }.
 ---@return table<integer, Range6[]>
 function LanguageTree:included_regions()
   if self._regions then
@@ -1087,7 +1089,7 @@ end
 
 --- Determines whether {range} is contained in the |LanguageTree|.
 ---
----@param range Range4 `{ start_line, start_col, end_line, end_col }`
+---@param range Range4
 ---@return boolean
 function LanguageTree:contains(range)
   for _, tree in pairs(self._trees) do
@@ -1108,7 +1110,7 @@ end
 
 --- Gets the tree that contains {range}.
 ---
----@param range Range4 `{ start_line, start_col, end_line, end_col }`
+---@param range Range4
 ---@param opts? vim.treesitter.LanguageTree.tree_for_range.Opts
 ---@return TSTree?
 function LanguageTree:tree_for_range(range, opts)
@@ -1135,7 +1137,7 @@ end
 
 --- Gets the smallest node that contains {range}.
 ---
----@param range Range4 `{ start_line, start_col, end_line, end_col }`
+---@param range Range4
 ---@param opts? vim.treesitter.LanguageTree.tree_for_range.Opts
 ---@return TSNode?
 function LanguageTree:node_for_range(range, opts)
@@ -1147,7 +1149,7 @@ end
 
 --- Gets the smallest named node that contains {range}.
 ---
----@param range Range4 `{ start_line, start_col, end_line, end_col }`
+---@param range Range4
 ---@param opts? vim.treesitter.LanguageTree.tree_for_range.Opts
 ---@return TSNode?
 function LanguageTree:named_node_for_range(range, opts)
@@ -1159,7 +1161,7 @@ end
 
 --- Gets the appropriate language that contains {range}.
 ---
----@param range Range4 `{ start_line, start_col, end_line, end_col }`
+---@param range Range4
 ---@return vim.treesitter.LanguageTree tree Managing {range}
 function LanguageTree:language_for_range(range)
   for _, child in pairs(self._children) do