refactor(lua): type annotations

runtime/doc/lua.txt

@@ -643,12 +643,14 @@ vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts})
                    tuple or string accepted by |getpos()|
       • {finish}   (`integer[]|string`) End of region as a (line, column)
                    tuple or string accepted by |getpos()|
-      • {opts}     (`table?`) Optional parameters
+      • {opts}     (`table?`) A table with the following fields:
-                   • regtype type of range (see |setreg()|, default charwise)
+                   • {regtype}? (`string`, default: `'charwise'`) Type of
-                   • inclusive boolean indicating whether the range is
+                     range. See |setreg()|
-                     end-inclusive (default false)
+                   • {inclusive}? (`boolean`, default: `false`) Indicates
-                   • priority number indicating priority of highlight (default
+                     whether the range is end-inclusive
-                     priorities.user)
+                   • {priority}? (`integer`, default:
+                     `vim.highlight.priorities.user`) Indicates priority of
+                     highlight
 
 
 ==============================================================================
@@ -2794,9 +2796,9 @@ vim.keymap.del({modes}, {lhs}, {opts})                      *vim.keymap.del()*
     Parameters: ~
       • {modes}  (`string|string[]`)
       • {lhs}    (`string`)
-      • {opts}   (`table?`) A table of optional arguments:
+      • {opts}   (`table?`) A table with the following fields:
-                 • "buffer": (integer|boolean) Remove a mapping from the given
+                 • {buffer}? (`integer|boolean`) Remove a mapping from the
-                   buffer. When `0` or `true`, use the current buffer.
+                   given buffer. When `0` or `true`, use the current buffer.
 
     See also: ~
       • |vim.keymap.set()|
@@ -2818,20 +2820,20 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts})                *vim.keymap.set()*
 <
 
     Parameters: ~
-      • {mode}  (`string|table`) Mode short-name, see |nvim_set_keymap()|. Can
+      • {mode}  (`string|string[]`) Mode short-name, see |nvim_set_keymap()|.
-                also be list of modes to create mapping on multiple modes.
+                Can also be list of modes to create mapping on multiple modes.
       • {lhs}   (`string`) Left-hand side |{lhs}| of the mapping.
       • {rhs}   (`string|function`) Right-hand side |{rhs}| of the mapping,
                 can be a Lua function.
-      • {opts}  (`table?`) Table of |:map-arguments|.
+      • {opts}  (`table?`) Table of |:map-arguments|. Same as
-                • Same as |nvim_set_keymap()| {opts}, except:
+                |nvim_set_keymap()| {opts}, except:
-                  • "replace_keycodes" defaults to `true` if "expr" is `true`.
+                • {replace_keycodes} defaults to `true` if "expr" is `true`.
-                  • "noremap": inverse of "remap" (see below).
+
-                • Also accepts:
+                Also accepts:
-                  • "buffer": (integer|boolean) Creates buffer-local mapping,
+                • {buffer}? (`integer|boolean`) Creates buffer-local mapping,
-                    `0` or `true` for current buffer.
+                  `0` or `true` for current buffer.
-                  • "remap": (boolean) Make the mapping recursive. Inverse of
+                • {remap}? (`boolean`, default: `false`) Make the mapping
-                    "noremap". Defaults to `false`.
+                  recursive. Inverse of {noremap}.
 
     See also: ~
       • |nvim_set_keymap()|
@@ -3566,7 +3568,7 @@ vim.secure.trust({opts})                                  *vim.secure.trust()*
     The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
 
     Parameters: ~
-      • {opts}  (`table?`) A table with the following fields:
+      • {opts}  (`table`) A table with the following fields:
                 • {action} (`'allow'|'deny'|'remove'`) - `'allow'` to add a
                   file to the trust database and trust it,
                 • `'deny'` to add a file to the trust database and deny it,
@@ -3777,7 +3779,6 @@ vim.version.range({spec})                                *vim.version.range()*
         (`table?`) A table with the following fields:
         • {from} (`vim.Version`)
         • {to}? (`vim.Version`)
-        • {has} (`fun(self: vim.VersionRangeversion: string|vim.Version)`)
 
     See also: ~
       • https://github.com/npm/node-semver#ranges

runtime/doc/treesitter.txt

@@ -978,7 +978,7 @@ add_directive({name}, {handler}, {opts})
 
     Parameters: ~
       • {name}     (`string`) Name of the directive, without leading #
-      • {handler}  (`function`)
+      • {handler}  (`fun(match: table<integer,TSNode[]>, pattern: integer, source: integer|string, predicate: any[], metadata: table)`)
                    • match: A table mapping capture IDs to a list of captured
                      nodes
                    • pattern: the index of the matching pattern in the query
@@ -986,10 +986,10 @@ add_directive({name}, {handler}, {opts})
                    • predicate: list of strings containing the full directive
                      being called, e.g. `(node (#set! conceal "-"))` would get
                      the predicate `{ "#set!", "conceal", "-" }`
-      • {opts}     (`table<string, any>`) Optional options:
+      • {opts}     (`table`) A table with the following fields:
-                   • force (boolean): Override an existing predicate of the
+                   • {force}? (`boolean`) Override an existing predicate of
-                     same name
+                     the same name
-                   • all (boolean): Use the correct implementation of the
+                   • {all}? (`boolean`) Use the correct implementation of the
                      match table where capture IDs map to a list of nodes
                      instead of a single node. Defaults to false (for backward
                      compatibility). This option will eventually become the
@@ -1001,13 +1001,13 @@ add_predicate({name}, {handler}, {opts})
 
     Parameters: ~
       • {name}     (`string`) Name of the predicate, without leading #
-      • {handler}  (`function`)
+      • {handler}  (`fun(match: table<integer,TSNode[]>, pattern: integer, source: integer|string, predicate: any[], metadata: table)`)
                    • see |vim.treesitter.query.add_directive()| for argument
                      meanings
-      • {opts}     (`table<string, any>`) Optional options:
+      • {opts}     (`table`) A table with the following fields:
-                   • force (boolean): Override an existing predicate of the
+                   • {force}? (`boolean`) Override an existing predicate of
-                     same name
+                     the same name
-                   • all (boolean): Use the correct implementation of the
+                   • {all}? (`boolean`) Use the correct implementation of the
                      match table where capture IDs map to a list of nodes
                      instead of a single node. Defaults to false (for backward
                      compatibility). This option will eventually become the
@@ -1079,13 +1079,13 @@ list_directives()                     *vim.treesitter.query.list_directives()*
     Lists the currently available directives to use in queries.
 
     Return: ~
-        (`string[]`) List of supported directives.
+        (`string[]`) Supported directives.
 
 list_predicates()                     *vim.treesitter.query.list_predicates()*
     Lists the currently available predicates to use in queries.
 
     Return: ~
-        (`string[]`) List of supported predicates.
+        (`string[]`) Supported predicates.
 
 omnifunc({findstart}, {base})                *vim.treesitter.query.omnifunc()*
     Omnifunc for completing node names and predicates in treesitter queries.
@@ -1319,7 +1319,7 @@ LanguageTree:language_for_range({range})
       • {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`
 
     Return: ~
-        (`vim.treesitter.LanguageTree`) Managing {range}
+        (`vim.treesitter.LanguageTree`) tree Managing {range}
 
                                          *LanguageTree:named_node_for_range()*
 LanguageTree:named_node_for_range({range}, {opts})
@@ -1327,12 +1327,12 @@ LanguageTree:named_node_for_range({range}, {opts})
 
     Parameters: ~
       • {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`
-      • {opts}   (`table?`) Optional keyword arguments:
+      • {opts}   (`table?`) A table with the following fields:
-                 • ignore_injections boolean Ignore injected languages
+                 • {ignore_injections}? (`boolean`, default: `true`) Ignore
-                   (default true)
+                   injected languages
 
     Return: ~
-        (`TSNode?`) Found node
+        (`TSNode?`)
 
 LanguageTree:parse({range})                             *LanguageTree:parse()*
     Recursively parse all regions in the language tree using
@@ -1359,8 +1359,9 @@ LanguageTree:register_cbs({cbs}, {recursive})
     Registers callbacks for the |LanguageTree|.
 
     Parameters: ~
-      • {cbs}        (`table`) An |nvim_buf_attach()|-like table argument with
+      • {cbs}        (`table<TSCallbackNameOn,function>`) An
-                     the following handlers:
+                     |nvim_buf_attach()|-like table argument with the
+                     following handlers:
                      • `on_bytes` : see |nvim_buf_attach()|, but this will be
                        called after the parsers callback.
                      • `on_changedtree` : a callback that will be called every
@@ -1387,9 +1388,9 @@ LanguageTree:tree_for_range({range}, {opts})
 
     Parameters: ~
       • {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`
-      • {opts}   (`table?`) Optional keyword arguments:
+      • {opts}   (`table?`) A table with the following fields:
-                 • ignore_injections boolean Ignore injected languages
+                 • {ignore_injections}? (`boolean`, default: `true`) Ignore
-                   (default true)
+                   injected languages
 
     Return: ~
         (`TSTree?`)

runtime/lua/vim/highlight.lua

@@ -40,6 +40,23 @@ M.priorities = {
   user = 200,
 }
 
+--- @class vim.highlight.range.Opts
+--- @inlinedoc
+---
+--- Type of range. See [setreg()]
+--- (default: `'charwise'`)
+--- @field regtype? string
+---
+--- Indicates whether the range is end-inclusive
+--- (default: `false`)
+--- @field inclusive? boolean
+---
+--- Indicates priority of highlight
+--- (default: `vim.highlight.priorities.user`)
+--- @field priority? integer
+---
+--- @field package _scoped? boolean
+
 --- Apply highlight group to range of text.
 ---
 ---@param bufnr integer Buffer number to apply highlighting to
@@ -47,10 +64,7 @@ M.priorities = {
 ---@param higroup string Highlight group to use for highlighting
 ---@param start integer[]|string Start of region as a (line, column) tuple or string accepted by |getpos()|
 ---@param finish integer[]|string End of region as a (line, column) tuple or string accepted by |getpos()|
----@param opts table|nil Optional parameters
+---@param opts? vim.highlight.range.Opts
----            - regtype type of range (see |setreg()|, default charwise)
----            - inclusive boolean indicating whether the range is end-inclusive (default false)
----            - priority number indicating priority of highlight (default priorities.user)
 function M.range(bufnr, ns, higroup, start, finish, opts)
   opts = opts or {}
   local regtype = opts.regtype or 'v'
@@ -80,8 +94,8 @@ function M.range(bufnr, ns, higroup, start, finish, opts)
 end
 
 local yank_ns = api.nvim_create_namespace('hlyank')
-local yank_timer
+local yank_timer --- @type uv.uv_timer_t?
-local yank_cancel
+local yank_cancel --- @type fun()?
 
 --- Highlight the yanked text
 ---
@@ -128,6 +142,7 @@ function M.on_yank(opts)
   local winid = vim.api.nvim_get_current_win()
   if yank_timer then
     yank_timer:close()
+    assert(yank_cancel)
     yank_cancel()
   end
 

runtime/lua/vim/keymap.lua

@@ -1,5 +1,20 @@
 local keymap = {}
 
+--- Table of |:map-arguments|.
+--- Same as |nvim_set_keymap()| {opts}, except:
+--- - {replace_keycodes} defaults to `true` if "expr" is `true`.
+---
+--- Also accepts:
+--- @class vim.keymap.set.Opts : vim.api.keyset.keymap
+--- @inlinedoc
+---
+--- Creates buffer-local mapping, `0` or `true` for current buffer.
+--- @field buffer? integer|boolean
+---
+--- Make the mapping recursive. Inverse of {noremap}.
+--- (Default: `false`)
+--- @field remap? boolean
+
 --- Adds a new |mapping|.
 --- Examples:
 ---
@@ -18,20 +33,12 @@ local keymap = {}
 --- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
 --- ```
 ---
----@param mode string|table    Mode short-name, see |nvim_set_keymap()|.
+---@param mode string|string[] Mode short-name, see |nvim_set_keymap()|.
 ---                            Can also be list of modes to create mapping on multiple modes.
 ---@param lhs string           Left-hand side |{lhs}| of the mapping.
 ---@param rhs string|function  Right-hand side |{rhs}| of the mapping, can be a Lua function.
 ---
----@param opts table|nil Table of |:map-arguments|.
+---@param opts? vim.keymap.set.Opts
----                      - Same as |nvim_set_keymap()| {opts}, except:
----                        - "replace_keycodes" defaults to `true` if "expr" is `true`.
----                        - "noremap": inverse of "remap" (see below).
----                      - Also accepts:
----                        - "buffer": (integer|boolean) Creates buffer-local mapping, `0` or `true`
----                        for current buffer.
----                        - "remap": (boolean) Make the mapping recursive. Inverse of "noremap".
----                        Defaults to `false`.
 ---@see |nvim_set_keymap()|
 ---@see |maparg()|
 ---@see |mapcheck()|
@@ -81,6 +88,13 @@ function keymap.set(mode, lhs, rhs, opts)
   end
 end
 
+--- @class vim.keymap.del.Opts
+--- @inlinedoc
+---
+--- Remove a mapping from the given buffer.
+--- When `0` or `true`, use the current buffer.
+--- @field buffer? integer|boolean
+
 --- Remove an existing mapping.
 --- Examples:
 ---
@@ -92,11 +106,8 @@ end
 ---
 ---@param modes string|string[]
 ---@param lhs string
----@param opts table|nil A table of optional arguments:
+---@param opts? vim.keymap.del.Opts
----                      - "buffer": (integer|boolean) Remove a mapping from the given buffer.
----                        When `0` or `true`, use the current buffer.
 ---@see |vim.keymap.set()|
----
 function keymap.del(modes, lhs, opts)
   vim.validate({
     mode = { modes, { 's', 't' } },
@@ -106,6 +117,7 @@ function keymap.del(modes, lhs, opts)
 
   opts = opts or {}
   modes = type(modes) == 'string' and { modes } or modes
+  --- @cast modes string[]
 
   local buffer = false ---@type false|integer
   if opts.buffer ~= nil then

runtime/lua/vim/secure.lua

@@ -126,7 +126,7 @@ end
 ---
 --- The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
 ---
----@param opts? vim.trust.opts
+---@param opts vim.trust.opts
 ---@return boolean success true if operation was successful
 ---@return string msg full path if operation was successful, else error message
 function M.trust(opts)

runtime/lua/vim/snippet.lua

@@ -254,9 +254,10 @@ local function display_choices(tabstop)
   assert(tabstop.choices, 'Tabstop has no choices')
 
   local start_col = tabstop:get_range()[2] + 1
-  local matches = vim.iter.map(function(choice)
+  local matches = {} --- @type table[]
-    return { word = choice }
+  for _, choice in ipairs(tabstop.choices) do
-  end, tabstop.choices)
+    matches[#matches + 1] = { word = choice }
+  end
 
   vim.defer_fn(function()
     vim.fn.complete(start_col, matches)
@@ -449,7 +450,9 @@ function M.expand(input)
     local shiftwidth = vim.fn.shiftwidth()
     local curbuf = vim.api.nvim_get_current_buf()
     local expandtab = vim.bo[curbuf].expandtab
-    local lines = vim.iter.map(function(i, line)
+
+    local lines = {} --- @type string[]
+    for i, line in ipairs(text_to_lines(text)) do
       -- Replace tabs by spaces.
       if expandtab then
         line = line:gsub('\t', (' '):rep(shiftwidth)) --- @type string
@@ -459,8 +462,8 @@ function M.expand(input)
         line = #line ~= 0 and base_indent .. line
           or (expandtab and (' '):rep(shiftwidth) or '\t'):rep(vim.fn.indent('.') / shiftwidth + 1)
       end
-      return line
+      lines[#lines + 1] = line
-    end, ipairs(text_to_lines(text)))
+    end
 
     table.insert(snippet_text, table.concat(lines, '\n'))
   end

runtime/lua/vim/termcap.lua

@@ -12,7 +12,7 @@ local M = {}
 --- emulator supports the XTGETTCAP sequence.
 ---
 --- @param caps string|table A terminal capability or list of capabilities to query
---- @param cb function(cap:string, found:bool, seq:string?) Callback function which is called for
+--- @param cb fun(cap:string, found:bool, seq:string?) Callback function which is called for
 ---           each capability in {caps}. {found} is set to true if the capability was found or false
 ---           otherwise. {seq} is the control sequence for the capability if found, or nil for
 ---           boolean capabilities.

runtime/lua/vim/text.lua

@@ -5,7 +5,7 @@ local M = {}
 --- Hex encode a string.
 ---
 --- @param str string String to encode
---- @return string Hex encoded string
+--- @return string : Hex encoded string
 function M.hexencode(str)
   local bytes = { str:byte(1, #str) }
   local enc = {} ---@type string[]
@@ -18,7 +18,7 @@ end
 --- Hex decode a string.
 ---
 --- @param enc string String to decode
---- @return string Decoded string
+--- @return string : Decoded string
 function M.hexdecode(enc)
   assert(#enc % 2 == 0, 'string must have an even number of hex characters')
   local str = {} ---@type string[]

runtime/lua/vim/treesitter/languagetree.lua

@@ -156,8 +156,10 @@ function LanguageTree:_set_logger()
 
   local lang = self:lang()
 
-  vim.fn.mkdir(vim.fn.stdpath('log'), 'p')
+  local logdir = vim.fn.stdpath('log') --[[@as string]]
-  local logfilename = vim.fs.joinpath(vim.fn.stdpath('log'), 'treesitter.log')
+
+  vim.fn.mkdir(logdir, 'p')
+  local logfilename = vim.fs.joinpath(logdir, 'treesitter.log')
 
   local logfile, openerr = io.open(logfilename, 'a+')
 
@@ -463,7 +465,7 @@ end
 --- Invokes the callback for each |LanguageTree| and its children recursively
 ---
 ---@param fn fun(tree: vim.treesitter.LanguageTree, lang: string)
----@param include_self boolean|nil Whether to include the invoking tree in the results
+---@param include_self? boolean Whether to include the invoking tree in the results
 function LanguageTree:for_each_child(fn, include_self)
   vim.deprecate('LanguageTree:for_each_child()', 'LanguageTree:children()', '0.11')
   if include_self then
@@ -796,7 +798,7 @@ function LanguageTree:_get_injection(match, metadata)
   local combined = metadata['injection.combined'] ~= nil
   local injection_lang = metadata['injection.language'] --[[@as string?]]
   local lang = metadata['injection.self'] ~= nil and self:lang()
-    or metadata['injection.parent'] ~= nil and self._parent
+    or metadata['injection.parent'] ~= nil and self._parent:lang()
     or (injection_lang and resolve_lang(injection_lang))
   local include_children = metadata['injection.include-children'] ~= nil
 
@@ -1058,20 +1060,19 @@ function LanguageTree:_on_detach(...)
   end
 end
 
---- Registers callbacks for the |LanguageTree|.
+--- Registers callbacks for the [LanguageTree].
----@param cbs table An |nvim_buf_attach()|-like table argument with the following handlers:
+---@param cbs table<TSCallbackNameOn,function> An [nvim_buf_attach()]-like table argument with the following handlers:
----           - `on_bytes` : see |nvim_buf_attach()|, but this will be called _after_ the parsers callback.
+---           - `on_bytes` : see [nvim_buf_attach()], but this will be called _after_ the parsers callback.
 ---           - `on_changedtree` : a callback that will be called every time the tree has syntactical changes.
 ---              It will be passed two arguments: a table of the ranges (as node ranges) that
 ---              changed and the changed tree.
 ---           - `on_child_added` : emitted when a child is added to the tree.
 ---           - `on_child_removed` : emitted when a child is removed from the tree.
----           - `on_detach` : emitted when the buffer is detached, see |nvim_buf_detach_event|.
+---           - `on_detach` : emitted when the buffer is detached, see [nvim_buf_detach_event].
 ---              Takes one argument, the number of the buffer.
 --- @param recursive? boolean Apply callbacks recursively for all children. Any new children will
 ---                           also inherit the callbacks.
 function LanguageTree:register_cbs(cbs, recursive)
-  ---@cast cbs table<TSCallbackNameOn,function>
   if not cbs then
     return
   end
@@ -1112,12 +1113,18 @@ function LanguageTree:contains(range)
   return false
 end
 
+--- @class vim.treesitter.LanguageTree.tree_for_range.Opts
+--- @inlinedoc
+---
+--- Ignore injected languages
+--- (default: `true`)
+--- @field ignore_injections? boolean
+
 --- Gets the tree that contains {range}.
 ---
 ---@param range Range4 `{ start_line, start_col, end_line, end_col }`
----@param opts table|nil Optional keyword arguments:
+---@param opts? vim.treesitter.LanguageTree.tree_for_range.Opts
----             - ignore_injections boolean Ignore injected languages (default true)
+---@return TSTree?
----@return TSTree|nil
 function LanguageTree:tree_for_range(range, opts)
   opts = opts or {}
   local ignore = vim.F.if_nil(opts.ignore_injections, true)
@@ -1143,9 +1150,8 @@ end
 --- Gets the smallest named node that contains {range}.
 ---
 ---@param range Range4 `{ start_line, start_col, end_line, end_col }`
----@param opts table|nil Optional keyword arguments:
+---@param opts? vim.treesitter.LanguageTree.tree_for_range.Opts
----             - ignore_injections boolean Ignore injected languages (default true)
+---@return TSNode?
----@return TSNode | nil Found node
 function LanguageTree:named_node_for_range(range, opts)
   local tree = self:tree_for_range(range, opts)
   if tree then
@@ -1156,7 +1162,7 @@ end
 --- Gets the appropriate language that contains {range}.
 ---
 ---@param range Range4 `{ start_line, start_col, end_line, end_col }`
----@return vim.treesitter.LanguageTree Managing {range}
+---@return vim.treesitter.LanguageTree tree Managing {range}
 function LanguageTree:language_for_range(range)
   for _, child in pairs(self._children) do
     if child:contains(range) then

runtime/lua/vim/treesitter/query.lua

@@ -88,7 +88,7 @@ end
 ---
 ---@param lang string Language to get query for
 ---@param query_name string Name of the query to load (e.g., "highlights")
----@param is_included (boolean|nil) Internal parameter, most of the time left as `nil`
+---@param is_included? boolean Internal parameter, most of the time left as `nil`
 ---@return string[] query_files List of files to load for given query and language
 function M.get_files(lang, query_name, is_included)
   local query_path = string.format('queries/%s/%s.scm', lang, query_name)
@@ -211,7 +211,7 @@ end
 ---@param lang string Language to use for the query
 ---@param query_name string Name of the query (e.g. "highlights")
 ---
----@return vim.treesitter.Query|nil : Parsed query. `nil` if no query files are found.
+---@return vim.treesitter.Query? : Parsed query. `nil` if no query files are found.
 M.get = vim.func._memoize('concat-2', function(lang, query_name)
   if explicit_queries[lang][query_name] then
     return explicit_queries[lang][query_name]
@@ -242,9 +242,9 @@ end)
 ---@param lang string Language to use for the query
 ---@param query string Query in s-expr syntax
 ---
----@return vim.treesitter.Query Parsed query
+---@return vim.treesitter.Query : Parsed query
 ---
----@see |vim.treesitter.query.get()|
+---@see [vim.treesitter.query.get()]
 M.parse = vim.func._memoize('concat-2', function(lang, query)
   language.add(lang)
 
@@ -618,20 +618,23 @@ local directive_handlers = {
   end,
 }
 
+--- @class vim.treesitter.query.add_predicate.Opts
+--- @inlinedoc
+---
+--- Override an existing predicate of the same name
+--- @field force? boolean
+---
+--- Use the correct implementation of the match table where capture IDs map to
+--- a list of nodes instead of a single node. Defaults to false (for backward
+--- compatibility). This option will eventually become the default and removed.
+--- @field all? boolean
+
 --- Adds a new predicate to be used in queries
 ---
 ---@param name string Name of the predicate, without leading #
----@param handler function(match: table<integer,TSNode[]>, pattern: integer, source: integer|string, predicate: any[], metadata: table)
+---@param handler fun(match: table<integer,TSNode[]>, pattern: integer, source: integer|string, predicate: any[], metadata: table)
 ---   - see |vim.treesitter.query.add_directive()| for argument meanings
----@param opts table<string, any> Optional options:
+---@param opts vim.treesitter.query.add_predicate.Opts
----                                 - force (boolean): Override an existing
----                                   predicate of the same name
----                                 - all (boolean): Use the correct
----                                   implementation of the match table where
----                                   capture IDs map to a list of nodes instead
----                                   of a single node. Defaults to false (for
----                                   backward compatibility). This option will
----                                   eventually become the default and removed.
 function M.add_predicate(name, handler, opts)
   -- Backward compatibility: old signature had "force" as boolean argument
   if type(opts) == 'boolean' then
@@ -669,20 +672,12 @@ end
 --- metadata table `metadata[capture_id].key = value`
 ---
 ---@param name string Name of the directive, without leading #
----@param handler function(match: table<integer,TSNode[]>, pattern: integer, source: integer|string, predicate: any[], metadata: table)
+---@param handler fun(match: table<integer,TSNode[]>, pattern: integer, source: integer|string, predicate: any[], metadata: table)
 ---   - match: A table mapping capture IDs to a list of captured nodes
 ---   - pattern: the index of the matching pattern in the query file
 ---   - predicate: list of strings containing the full directive being called, e.g.
 ---     `(node (#set! conceal "-"))` would get the predicate `{ "#set!", "conceal", "-" }`
----@param opts table<string, any> Optional options:
+---@param opts vim.treesitter.query.add_predicate.Opts
----                                 - force (boolean): Override an existing
----                                   predicate of the same name
----                                 - all (boolean): Use the correct
----                                   implementation of the match table where
----                                   capture IDs map to a list of nodes instead
----                                   of a single node. Defaults to false (for
----                                   backward compatibility). This option will
----                                   eventually become the default and removed.
 function M.add_directive(name, handler, opts)
   -- Backward compatibility: old signature had "force" as boolean argument
   if type(opts) == 'boolean' then
@@ -711,13 +706,13 @@ function M.add_directive(name, handler, opts)
 end
 
 --- Lists the currently available directives to use in queries.
----@return string[] List of supported directives.
+---@return string[] : Supported directives.
 function M.list_directives()
   return vim.tbl_keys(directive_handlers)
 end
 
 --- Lists the currently available predicates to use in queries.
----@return string[] List of supported predicates.
+---@return string[] : Supported predicates.
 function M.list_predicates()
   return vim.tbl_keys(predicate_handlers)
 end
@@ -792,8 +787,8 @@ end
 --- Returns the start and stop value if set else the node's range.
 -- When the node's range is used, the stop is incremented by 1
 -- to make the search inclusive.
----@param start integer|nil
+---@param start integer?
----@param stop integer|nil
+---@param stop integer?
 ---@param node TSNode
 ---@return integer, integer
 local function value_or_node_range(start, stop, node)

scripts/gen_vimdoc.lua

@@ -488,10 +488,12 @@ local function inline_type(obj, classes)
 
   local desc_append = {}
   for _, f in ipairs(cls.fields) do
-    local fdesc, default = get_default(f.desc)
+    if not f.access then
-    local fty = render_type(f.type, nil, default)
+      local fdesc, default = get_default(f.desc)
-    local fnm = fmt_field_name(f.name)
+      local fty = render_type(f.type, nil, default)
-    table.insert(desc_append, table.concat({ '-', fnm, fty, fdesc }, ' '))
+      local fnm = fmt_field_name(f.name)
+      table.insert(desc_append, table.concat({ '-', fnm, fty, fdesc }, ' '))
+    end
   end
 
   desc = desc .. '\n' .. table.concat(desc_append, '\n')