From 0a1212ef94547f04db789a660639fab6837e00ce Mon Sep 17 00:00:00 2001 From: Yi Ming Date: Tue, 6 Aug 2024 19:28:42 +0800 Subject: [PATCH] docs(treesitter): generate inline docs for `Range`s docs(treesitter): in-place parameter description docs(treesitter): remove internal type names docs(treesitter): add missing private annotation --- runtime/doc/treesitter.txt | 45 +++++++++++++++++---- runtime/lua/vim/treesitter/_range.lua | 4 ++ runtime/lua/vim/treesitter/languagetree.lua | 12 +++--- 3 files changed, 48 insertions(+), 13 deletions(-) diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 97f77c9e31..c8fc2743af 100644 --- a/runtime/doc/treesitter.txt +++ b/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`) @@ -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 diff --git a/runtime/lua/vim/treesitter/_range.lua b/runtime/lua/vim/treesitter/_range.lua index 8d727c3c52..82ab8517aa 100644 --- a/runtime/lua/vim/treesitter/_range.lua +++ b/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 diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua index 03803f5869..d43a0a5d0b 100644 --- a/runtime/lua/vim/treesitter/languagetree.lua +++ b/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 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