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.

1 files changed, 30 insertions, 22 deletions

diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 57272dbd60..6c7f713fd7 100644
--- 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)