docs: improve/add documentation of Lua types

- Added `@inlinedoc` so single use Lua types can be inlined into the functions docs. E.g. ```lua --- @class myopts --- @inlinedoc --- --- Documentation for some field --- @field somefield integer --- @param opts myOpts function foo(opts) end ``` Will be rendered as ``` foo(opts) Parameters: - {opts} (table) Object with the fields: - somefield (integer) Documentation for some field ``` - Marked many classes with with `@nodoc` or `(private)`. We can eventually introduce these when we want to.
2026-05-04 21:15:09 +00:00 · 2024-02-27 15:20:32 +00:00
parent 813dd36b72
commit a5fe8f59d9
47 changed files with 2014 additions and 1450 deletions
--- a/runtime/lua/vim/treesitter/_query_linter.lua
+++ b/runtime/lua/vim/treesitter/_query_linter.lua
@@ -45,7 +45,7 @@ local function guess_query_lang(buf)
 end

 --- @param buf integer
--- @param opts QueryLinterOpts|QueryLinterNormalizedOpts|nil
+--- @param opts vim.treesitter.query.lint.Opts|QueryLinterNormalizedOpts|nil
 --- @return QueryLinterNormalizedOpts
 local function normalize_opts(buf, opts)
  opts = opts or {}
@@ -122,7 +122,7 @@ local parse = vim.func._memoize(hash_parse, function(node, buf, lang)
 end)

 --- @param buf integer
--- @param match TSMatch
+--- @param match vim.treesitter.query.TSMatch
 --- @param query Query
 --- @param lang_context QueryLinterLanguageContext
 --- @param diagnostics Diagnostic[]
@@ -153,7 +153,7 @@ end

 --- @private
 --- @param buf integer Buffer to lint
--- @param opts QueryLinterOpts|QueryLinterNormalizedOpts|nil Options for linting
+--- @param opts vim.treesitter.query.lint.Opts|QueryLinterNormalizedOpts|nil Options for linting
 function M.lint(buf, opts)
  if buf == 0 then
    buf = api.nvim_get_current_buf()
--- a/runtime/lua/vim/treesitter/dev.lua
+++ b/runtime/lua/vim/treesitter/dev.lua
@@ -1,23 +1,21 @@
 local api = vim.api

---@class TSDevModule
 local M = {}

---@private
---@class TSTreeView
+---@class (private) vim.treesitter.dev.TSTreeView
 ---@field ns integer API namespace
---@field opts TSTreeViewOpts
---@field nodes TSP.Node[]
---@field named TSP.Node[]
+---@field opts vim.treesitter.dev.TSTreeViewOpts
+---@field nodes vim.treesitter.dev.Node[]
+---@field named vim.treesitter.dev.Node[]
 local TSTreeView = {}

 ---@private
---@class TSTreeViewOpts
+---@class (private) vim.treesitter.dev.TSTreeViewOpts
 ---@field anon boolean If true, display anonymous nodes.
 ---@field lang boolean If true, display the language alongside each node.
 ---@field indent number Number of spaces to indent nested lines.

---@class TSP.Node
+---@class (private) vim.treesitter.dev.Node
 ---@field node TSNode Treesitter node
 ---@field field string? Node field
 ---@field depth integer Depth of this node in the tree
@@ -25,7 +23,7 @@ local TSTreeView = {}
 ---                    inspector is drawn.
 ---@field lang string Source language of this node

---@class TSP.Injection
+---@class (private) vim.treesitter.dev.Injection
 ---@field lang string Source language of this injection
 ---@field root TSNode Root node of the injection

@@ -45,9 +43,9 @@ local TSTreeView = {}
 ---@param depth integer Current recursion depth
 ---@param field string|nil The field of the current node
 ---@param lang string Language of the tree currently being traversed
---@param injections table<string, TSP.Injection> Mapping of node ids to root nodes
+---@param injections table<string, vim.treesitter.dev.Injection> Mapping of node ids to root nodes
 ---                  of injected language trees (see explanation above)
---@param tree TSP.Node[] Output table containing a list of tables each representing a node in the tree
+---@param tree vim.treesitter.dev.Node[] Output table containing a list of tables each representing a node in the tree
 local function traverse(node, depth, field, lang, injections, tree)
  table.insert(tree, {
    node = node,
@@ -73,7 +71,7 @@ end
 ---@param bufnr integer Source buffer number
 ---@param lang string|nil Language of source buffer
 ---
---@return TSTreeView|nil
+---@return vim.treesitter.dev.TSTreeView|nil
 ---@return string|nil Error message, if any
 ---
 ---@package
@@ -88,7 +86,7 @@ function TSTreeView:new(bufnr, lang)
  -- the primary tree that contains that root. Add a mapping from the node in the primary tree to
  -- the root in the child tree to the {injections} table.
  local root = parser:parse(true)[1]:root()
-  local injections = {} ---@type table<string, TSP.Injection>
+  local injections = {} ---@type table<string, vim.treesitter.dev.Injection>

  parser:for_each_tree(function(parent_tree, parent_ltree)
    local parent = parent_tree:root()
@@ -109,7 +107,7 @@ function TSTreeView:new(bufnr, lang)

  local nodes = traverse(root, 0, nil, parser:lang(), injections, {})

-  local named = {} ---@type TSP.Node[]
+  local named = {} ---@type vim.treesitter.dev.Node[]
  for _, v in ipairs(nodes) do
    if v.node:named() then
      named[#named + 1] = v
@@ -120,7 +118,7 @@ function TSTreeView:new(bufnr, lang)
    ns = api.nvim_create_namespace('treesitter/dev-inspect'),
    nodes = nodes,
    named = named,
-    ---@type TSTreeViewOpts
+    ---@type vim.treesitter.dev.TSTreeViewOpts
    opts = {
      anon = false,
      lang = false,
@@ -171,7 +169,7 @@ end

 --- Updates the cursor position in the inspector to match the node under the cursor.
 ---
--- @param treeview TSTreeView
+--- @param treeview vim.treesitter.dev.TSTreeView
 --- @param lang string
 --- @param source_buf integer
 --- @param inspect_buf integer
@@ -278,7 +276,7 @@ end
 --- The node number is dependent on whether or not anonymous nodes are displayed.
 ---
 ---@param i integer Node number to get
---@return TSP.Node
+---@return vim.treesitter.dev.Node
 ---@package
 function TSTreeView:get(i)
  local t = self.opts.anon and self.nodes or self.named
@@ -287,7 +285,7 @@ end

 --- Iterate over all of the nodes in this View.
 ---
---@return (fun(): integer, TSP.Node) Iterator over all nodes in this View
+---@return (fun(): integer, vim.treesitter.dev.Node) Iterator over all nodes in this View
 ---@return table
 ---@return integer
 ---@package
@@ -295,22 +293,31 @@ function TSTreeView:iter()
  return ipairs(self.opts.anon and self.nodes or self.named)
 end

--- @class InspectTreeOpts
--- @field lang string? The language of the source buffer. If omitted, the
---                     filetype of the source buffer is used.
--- @field bufnr integer? Buffer to draw the tree into. If omitted, a new
---                       buffer is created.
--- @field winid integer? Window id to display the tree buffer in. If omitted,
---                       a new window is created with {command}.
--- @field command string? Vimscript command to create the window. Default
---                       value is "60vnew". Only used when {winid} is nil.
--- @field title (string|fun(bufnr:integer):string|nil) Title of the window. If a
---                       function, it accepts the buffer number of the source
---                       buffer as its only argument and should return a string.
+--- @class vim.treesitter.dev.inspect_tree.Opts
+--- @inlinedoc
+---
+--- The language of the source buffer. If omitted, the filetype of the source
+--- buffer is used.
+--- @field lang string?
+---
+--- Buffer to draw the tree into. If omitted, a new buffer is created.
+--- @field bufnr integer?
+---
+--- Window id to display the tree buffer in. If omitted, a new window is
+--- created with {command}.
+--- @field winid integer?
+---
+--- Vimscript command to create the window. Default value is "60vnew".
+--- Only used when {winid} is nil.
+--- @field command string?
+---
+--- Title of the window. If a function, it accepts the buffer number of the
+--- source buffer as its only argument and should return a string.
+--- @field title (string|fun(bufnr:integer):string|nil)

 --- @private
 ---
--- @param opts InspectTreeOpts?
+--- @param opts vim.treesitter.dev.inspect_tree.Opts?
 function M.inspect_tree(opts)
  vim.validate({
    opts = { opts, 't', true },
--- a/runtime/lua/vim/treesitter/highlighter.lua
+++ b/runtime/lua/vim/treesitter/highlighter.lua
@@ -4,9 +4,9 @@ local Range = require('vim.treesitter._range')

 local ns = api.nvim_create_namespace('treesitter/highlighter')

---@alias vim.treesitter.highlighter.Iter fun(end_line: integer|nil): integer, TSNode, TSMetadata
+---@alias vim.treesitter.highlighter.Iter fun(end_line: integer|nil): integer, TSNode, vim.treesitter.query.TSMetadata

---@class vim.treesitter.highlighter.Query
+---@class (private) vim.treesitter.highlighter.Query
 ---@field private _query vim.treesitter.Query?
 ---@field private lang string
 ---@field private hl_cache table<integer,integer>
@@ -52,22 +52,23 @@ function TSHighlighterQuery:query()
  return self._query
 end

---@class vim.treesitter.highlighter.State
+---@class (private) vim.treesitter.highlighter.State
 ---@field tstree TSTree
 ---@field next_row integer
 ---@field iter vim.treesitter.highlighter.Iter?
 ---@field highlighter_query vim.treesitter.highlighter.Query

+---@nodoc
 ---@class vim.treesitter.highlighter
 ---@field active table<integer,vim.treesitter.highlighter>
 ---@field bufnr integer
---@field orig_spelloptions string
+---@field private orig_spelloptions string
 --- A map of highlight states.
 --- This state is kept during rendering across each line update.
---@field _highlight_states vim.treesitter.highlighter.State[]
---@field _queries table<string,vim.treesitter.highlighter.Query>
---@field tree LanguageTree
---@field redraw_count integer
+---@field private _highlight_states vim.treesitter.highlighter.State[]
+---@field private _queries table<string,vim.treesitter.highlighter.Query>
+---@field tree vim.treesitter.LanguageTree
+---@field private redraw_count integer
 local TSHighlighter = {
  active = {},
 }
@@ -78,7 +79,7 @@ TSHighlighter.__index = TSHighlighter
 ---
 --- Creates a highlighter for `tree`.
 ---
---@param tree LanguageTree parser object to use for highlighting
+---@param tree vim.treesitter.LanguageTree parser object to use for highlighting
 ---@param opts (table|nil) Configuration of the highlighter:
 ---           - queries table overwrite queries used by the highlighter
 ---@return vim.treesitter.highlighter Created highlighter object
--- a/runtime/lua/vim/treesitter/language.lua
+++ b/runtime/lua/vim/treesitter/language.lua
@@ -56,10 +56,17 @@ function M.require_language(lang, path, silent, symbol_name)
  return true
 end

---@class vim.treesitter.language.RequireLangOpts
---@field path? string
---@field silent? boolean
+---@class vim.treesitter.language.add.Opts
+---@inlinedoc
+---
+---Default filetype the parser should be associated with.
+---(Default: {lang})
 ---@field filetype? string|string[]
+---
+---Optional path the parser is located at
+---@field path? string
+---
+---Internal symbol name for the language to load
 ---@field symbol_name? string

 --- Load parser with name {lang}
@@ -67,13 +74,8 @@ end
 --- Parsers are searched in the `parser` runtime directory, or the provided {path}
 ---
 ---@param lang string Name of the parser (alphanumerical and `_` only)
---@param opts (table|nil) Options:
---                        - filetype (string|string[]) Default filetype the parser should be associated with.
---                          Defaults to {lang}.
---                        - path (string|nil) Optional path the parser is located at
---                        - symbol_name (string|nil) Internal symbol name for the language to load
+---@param opts? vim.treesitter.language.add.Opts Options:
 function M.add(lang, opts)
-  ---@cast opts vim.treesitter.language.RequireLangOpts
  opts = opts or {}
  local path = opts.path
  local filetype = opts.filetype or lang
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/runtime/lua/vim/treesitter/languagetree.lua
@@ -67,10 +67,11 @@ local TSCallbackNames = {
  on_child_removed = 'child_removed',
 }

---@class LanguageTree
+---@nodoc
+---@class vim.treesitter.LanguageTree
 ---@field private _callbacks table<TSCallbackName,function[]> Callback handlers
 ---@field package _callbacks_rec table<TSCallbackName,function[]> Callback handlers (recursive)
---@field private _children table<string,LanguageTree> Injected languages
+---@field private _children table<string,vim.treesitter.LanguageTree> Injected languages
 ---@field private _injection_query Query Queries defining injected languages
 ---@field private _injections_processed boolean
 ---@field private _opts table Options
@@ -89,7 +90,9 @@ local TSCallbackNames = {
 ---@field private _logfile? file*
 local LanguageTree = {}

---@class LanguageTreeOpts
+---Optional arguments:
+---@class vim.treesitter.LanguageTree.new.Opts
+---@inlinedoc
 ---@field queries table<string,string>  -- Deprecated
 ---@field injections table<string,string>

@@ -102,14 +105,11 @@ LanguageTree.__index = LanguageTree
 ---
 ---@param source (integer|string) Buffer or text string to parse
 ---@param lang string Root language of this tree
---@param opts (table|nil) Optional arguments:
---             - injections table Map of language to injection query strings. Overrides the
---                                built-in runtime file searching for language injections.
+---@param opts vim.treesitter.LanguageTree.new.Opts?
 ---@param parent_lang? string Parent language name of this tree
---@return LanguageTree parser object
+---@return vim.treesitter.LanguageTree parser object
 function LanguageTree.new(source, lang, opts, parent_lang)
  language.add(lang)
-  ---@type LanguageTreeOpts
  opts = opts or {}

  if source == 0 then
@@ -118,7 +118,7 @@ function LanguageTree.new(source, lang, opts, parent_lang)

  local injections = opts.injections or {}

-  --- @type LanguageTree
+  --- @type vim.treesitter.LanguageTree
  local self = {
    _source = source,
    _lang = lang,
@@ -194,7 +194,7 @@ local function tcall(f, ...)
 end

 ---@private
---@vararg any
+---@param ... any
 function LanguageTree:_log(...)
  if not self._logger then
    return
@@ -464,7 +464,7 @@ end
 ---            add recursion yourself if needed.
 --- Invokes the callback for each |LanguageTree| and its children recursively
 ---
---@param fn fun(tree: LanguageTree, lang: string)
+---@param fn fun(tree: vim.treesitter.LanguageTree, lang: string)
 ---@param include_self boolean|nil 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')
@@ -481,7 +481,7 @@ end
 ---
 --- Note: This includes the invoking tree's child trees as well.
 ---
---@param fn fun(tree: TSTree, ltree: LanguageTree)
+---@param fn fun(tree: TSTree, ltree: vim.treesitter.LanguageTree)
 function LanguageTree:for_each_tree(fn)
  for _, tree in pairs(self._trees) do
    fn(tree, self)
@@ -498,7 +498,7 @@ end
 ---
 ---@private
 ---@param lang string Language to add.
---@return LanguageTree injected
+---@return vim.treesitter.LanguageTree injected
 function LanguageTree:add_child(lang)
  if self._children[lang] then
    self:remove_child(lang)
@@ -668,7 +668,7 @@ end

 ---@param node TSNode
 ---@param source string|integer
---@param metadata TSMetadata
+---@param metadata vim.treesitter.query.TSMetadata
 ---@param include_children boolean
 ---@return Range6[]
 local function get_node_ranges(node, source, metadata, include_children)
@@ -702,13 +702,14 @@ local function get_node_ranges(node, source, metadata, include_children)
  return ranges
 end

---@class TSInjectionElem
+---@nodoc
+---@class vim.treesitter.languagetree.InjectionElem
 ---@field combined boolean
 ---@field regions Range6[][]

---@alias TSInjection table<string,table<integer,TSInjectionElem>>
+---@alias vim.treesitter.languagetree.Injection table<string,table<integer,vim.treesitter.languagetree.InjectionElem>>

---@param t table<integer,TSInjection>
+---@param t table<integer,vim.treesitter.languagetree.Injection>
 ---@param tree_index integer
 ---@param pattern integer
 ---@param lang string
@@ -783,7 +784,7 @@ end
 --- Extract injections according to:
 --- https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection
 ---@param match table<integer,TSNode[]>
---@param metadata TSMetadata
+---@param metadata vim.treesitter.query.TSMetadata
 ---@return string?, boolean, Range6[]
 function LanguageTree:_get_injection(match, metadata)
  local ranges = {} ---@type Range6[]
@@ -836,7 +837,7 @@ function LanguageTree:_get_injections()
    return {}
  end

-  ---@type table<integer,TSInjection>
+  ---@type table<integer,vim.treesitter.languagetree.Injection>
  local injections = {}

  for index, tree in pairs(self._trees) do
@@ -1150,7 +1151,7 @@ end
 --- Gets the appropriate language that contains {range}.
 ---
 ---@param range Range4 `{ start_line, start_col, end_line, end_col }`
---@return LanguageTree Managing {range}
+---@return vim.treesitter.LanguageTree Managing {range}
 function LanguageTree:language_for_range(range)
  for _, child in pairs(self._children) do
    if child:contains(range) then
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -3,6 +3,7 @@ local language = require('vim.treesitter.language')

 local M = {}

+---@nodoc
 ---Parsed query, see |vim.treesitter.query.parse()|
 ---
 ---@class vim.treesitter.Query
@@ -31,6 +32,7 @@ function Query.new(lang, ts_query)
  return self
 end

+---@nodoc
 ---Information for Query, see |vim.treesitter.query.parse()|
 ---@class vim.treesitter.QueryInfo
 ---
@@ -296,7 +298,7 @@ end
 --- handling the "any" vs "all" semantics. They are called from the
 --- predicate_handlers table with the appropriate arguments for each predicate.
 local impl = {
-  --- @param match TSMatch
+  --- @param match vim.treesitter.query.TSMatch
  --- @param source integer|string
  --- @param predicate any[]
  --- @param any boolean
@@ -331,7 +333,7 @@ local impl = {
    return not any
  end,

-  --- @param match TSMatch
+  --- @param match vim.treesitter.query.TSMatch
  --- @param source integer|string
  --- @param predicate any[]
  --- @param any boolean
@@ -371,7 +373,7 @@ local impl = {
      end,
    })

-    --- @param match TSMatch
+    --- @param match vim.treesitter.query.TSMatch
    --- @param source integer|string
    --- @param predicate any[]
    --- @param any boolean
@@ -394,7 +396,7 @@ local impl = {
    end
  end)(),

-  --- @param match TSMatch
+  --- @param match vim.treesitter.query.TSMatch
  --- @param source integer|string
  --- @param predicate any[]
  --- @param any boolean
@@ -421,12 +423,13 @@ local impl = {
  end,
 }

---@class TSMatch
+---@nodoc
+---@class vim.treesitter.query.TSMatch
 ---@field pattern? integer
 ---@field active? boolean
 ---@field [integer] TSNode[]

---@alias TSPredicate fun(match: TSMatch, pattern: integer, source: integer|string, predicate: any[]): boolean
+---@alias TSPredicate fun(match: vim.treesitter.query.TSMatch, pattern: integer, source: integer|string, predicate: any[]): boolean

 -- Predicate handler receive the following arguments
 -- (match, pattern, bufnr, predicate)
@@ -534,13 +537,14 @@ local predicate_handlers = {
 predicate_handlers['vim-match?'] = predicate_handlers['match?']
 predicate_handlers['any-vim-match?'] = predicate_handlers['any-match?']

---@class TSMetadata
+---@nodoc
+---@class vim.treesitter.query.TSMetadata
 ---@field range? Range
 ---@field conceal? string
---@field [integer] TSMetadata
+---@field [integer] vim.treesitter.query.TSMetadata
 ---@field [string] integer|string

---@alias TSDirective fun(match: TSMatch, _, _, predicate: (string|integer)[], metadata: TSMetadata)
+---@alias TSDirective fun(match: vim.treesitter.query.TSMatch, _, _, predicate: (string|integer)[], metadata: vim.treesitter.query.TSMetadata)

 -- Predicate handler receive the following arguments
 -- (match, pattern, bufnr, predicate)
@@ -767,7 +771,7 @@ local function is_directive(name)
 end

 ---@private
---@param match TSMatch
+---@param match vim.treesitter.query.TSMatch
 ---@param pattern integer
 ---@param source integer|string
 function Query:match_preds(match, pattern, source)
@@ -806,8 +810,8 @@ function Query:match_preds(match, pattern, source)
 end

 ---@private
---@param match TSMatch
---@param metadata TSMetadata
+---@param match vim.treesitter.query.TSMatch
+---@param metadata vim.treesitter.query.TSMetadata
 function Query:apply_directives(match, pattern, source, metadata)
  local preds = self.info.patterns[pattern]

@@ -871,7 +875,7 @@ end
 ---@param start? integer Starting line for the search. Defaults to `node:start()`.
 ---@param stop? integer Stopping line for the search (end-exclusive). Defaults to `node:end_()`.
 ---
---@return (fun(end_line: integer|nil): integer, TSNode, TSMetadata):
+---@return (fun(end_line: integer|nil): integer, TSNode, vim.treesitter.query.TSMetadata):
 ---        capture id, capture node, metadata
 function Query:iter_captures(node, source, start, stop)
  if type(source) == 'number' and source == 0 then
@@ -880,7 +884,7 @@ function Query:iter_captures(node, source, start, stop)

  start, stop = value_or_node_range(start, stop, node)

-  local raw_iter = node:_rawquery(self.query, true, start, stop) ---@type fun(): integer, TSNode, TSMatch
+  local raw_iter = node:_rawquery(self.query, true, start, stop) ---@type fun(): integer, TSNode, vim.treesitter.query.TSMatch
  local function iter(end_line)
    local capture, captured_node, match = raw_iter()
    local metadata = {}
@@ -952,7 +956,7 @@ function Query:iter_matches(node, source, start, stop, opts)

  start, stop = value_or_node_range(start, stop, node)

-  local raw_iter = node:_rawquery(self.query, false, start, stop, opts) ---@type fun(): integer, TSMatch
+  local raw_iter = node:_rawquery(self.query, false, start, stop, opts) ---@type fun(): integer, vim.treesitter.query.TSMatch
  local function iter()
    local pattern, match = raw_iter()
    local metadata = {}
@@ -982,9 +986,16 @@ function Query:iter_matches(node, source, start, stop, opts)
  return iter
 end

---@class QueryLinterOpts
---@field langs (string|string[]|nil)
---@field clear (boolean)
+--- Optional keyword arguments:
+--- @class vim.treesitter.query.lint.Opts
+--- @inlinedoc
+---
+--- Language(s) to use for checking the query.
+--- If multiple languages are specified, queries are validated for all of them
+--- @field langs? string|string[]
+---
+--- Just clear current lint errors
+--- @field clear boolean

 --- Lint treesitter queries using installed parser, or clear lint errors.
 ---
@@ -999,10 +1010,7 @@ end
 --- of the query file, e.g., if the path ends in `/lua/highlights.scm`, the parser for the
 --- `lua` language will be used.
 ---@param buf (integer) Buffer handle
---@param opts? QueryLinterOpts (table) Optional keyword arguments:
---   - langs (string|string[]|nil) Language(s) to use for checking the query.
---            If multiple languages are specified, queries are validated for all of them
---   - clear (boolean) if `true`, just clear current lint errors
+---@param opts? vim.treesitter.query.lint.Opts
 function M.lint(buf, opts)
  if opts and opts.clear then
    vim.treesitter._query_linter.clear(buf)