style: fill in missing code docs wherever applicable

lua/nvim-treesitter/query.lua

@@ -11,10 +11,10 @@ local EMPTY_ITER = function() end
 
 M.built_in_query_groups = { "highlights", "locals", "folds", "indents", "injections" }
 
---- Creates a function that checks whether a given query exists
---- for a specific language.
+-- Creates a function that checks whether a given query exists
+-- for a specific language.
 ---@param query string
----@return function(string): boolean
+---@return fun(string): boolean
 local function get_query_guard(query)
   return function(lang)
     return M.has_query_files(lang, query)
@@ -49,6 +49,9 @@ do
     })
   end
 
+  ---@param bufnr integer
+  ---@param query_group string
+  ---@return any
   function M.get_matches(bufnr, query_group)
     bufnr = bufnr or api.nvim_get_current_buf()
     local cached_local = query_cache.get(query_group, bufnr)
@@ -94,9 +97,10 @@ do
   end
 
   -- cache will auto set the table for each lang if it is nil
+  ---@type table<string, table<string, Query>>
   local cache = setmetatable({}, mt)
 
-  --- Same as `vim.treesitter.query` except will return cached values
+  -- Same as `vim.treesitter.query` except will return cached values
   ---@param lang string
   ---@param query_name string
   function M.get_query(lang, query_name)
@@ -107,12 +111,13 @@ do
     return cache[lang][query_name]
   end
 
-  --- Invalidates the query file cache.
-  --- If lang and query_name is both present, will reload for only the lang and query_name.
-  --- If only lang is present, will reload all query_names for that lang
-  --- If none are present, will reload everything
-  ---@param lang string
-  ---@param query_name string
+  -- Invalidates the query file cache.
+  --
+  -- If lang and query_name is both present, will reload for only the lang and query_name.
+  -- If only lang is present, will reload all query_names for that lang
+  -- If none are present, will reload everything
+  ---@param lang? string
+  ---@param query_name? string
   function M.invalidate_query_cache(lang, query_name)
     if lang and query_name then
       cache[lang][query_name] = nil
@@ -137,7 +142,7 @@ do
   end
 end
 
---- This function is meant for an autocommand and not to be used. Only use if file is a query file.
+-- This function is meant for an autocommand and not to be used. Only use if file is a query file.
 ---@param fname string
 function M.invalidate_query_file(fname)
   local fnamemodify = vim.fn.fnamemodify
@@ -145,14 +150,14 @@ function M.invalidate_query_file(fname)
 end
 
 ---@class QueryInfo
----@field root LanguageTree
+---@field root TSNode
 ---@field source integer
 ---@field start integer
 ---@field stop integer
 
 ---@param bufnr integer
 ---@param query_name string
----@param root LanguageTree
+---@param root TSNode
 ---@param root_lang string|nil
 ---@return Query|nil, QueryInfo|nil
 local function prepare_query(bufnr, query_name, root, root_lang)
@@ -214,15 +219,21 @@ end
 ---@param end_row integer
 function M.iter_prepared_matches(query, qnode, bufnr, start_row, end_row)
   -- A function that splits  a string on '.'
-  local function split(string)
+  ---@param to_split string
+  ---@return string[]
+  local function split(to_split)
     local t = {}
-    for str in string.gmatch(string, "([^.]+)") do
+    for str in string.gmatch(to_split, "([^.]+)") do
       table.insert(t, str)
     end
 
     return t
   end
+
   -- Given a path (i.e. a List(String)) this functions inserts value at path
+  ---@param object any
+  ---@param path string[]
+  ---@param value any
   local function insert_to_path(object, path, value)
     local curr_obj = object
 
@@ -256,6 +267,7 @@ function M.iter_prepared_matches(query, qnode, bufnr, start_row, end_row)
       end
 
       -- Add some predicates for testing
+      ---@type string[][] ( TODO: make pred type so this can be pred[])
       local preds = query.info.patterns[pattern]
       if preds then
         for _, pred in pairs(preds) do
@@ -279,22 +291,22 @@ function M.iter_prepared_matches(query, qnode, bufnr, start_row, end_row)
   return iterator
 end
 
---- Return all nodes corresponding to a specific capture path (like @definition.var, @reference.type)
----Works like M.get_references or M.get_scopes except you can choose the capture
----Can also be a nested capture like @definition.function to get all nodes defining a function.
----
+-- Return all nodes corresponding to a specific capture path (like @definition.var, @reference.type)
+-- Works like M.get_references or M.get_scopes except you can choose the capture
+-- Can also be a nested capture like @definition.function to get all nodes defining a function.
+--
 ---@param bufnr integer the buffer
 ---@param captures string|string[]
 ---@param query_group string the name of query group (highlights or injections for example)
----@param root LanguageTree|nil node from where to start the search
+---@param root TSNode|nil node from where to start the search
 ---@param lang string|nil the language from where to get the captures.
----            Root nodes can have several languages.
+---              Root nodes can have several languages.
 ---@return table|nil
 function M.get_capture_matches(bufnr, captures, query_group, root, lang)
   if type(captures) == "string" then
     captures = { captures }
   end
-  local strip_captures = {}
+  local strip_captures = {} ---@type string[]
   for i, capture in ipairs(captures) do
     if capture:sub(1, 1) ~= "@" then
       error 'Captures must start with "@"'
@@ -342,14 +354,21 @@ function M.iter_captures(bufnr, query_name, root, lang)
   return wrapped_iter
 end
 
+---@param bufnr integer
+---@param capture_string string
+---@param query_group string
+---@param filter_predicate fun(match: table): boolean
+---@param scoring_function fun(match: table): number
+---@param root TSNode
+---@return table|unknown
 function M.find_best_match(bufnr, capture_string, query_group, filter_predicate, scoring_function, root)
   if string.sub(capture_string, 1, 1) == "@" then
     --remove leading "@"
     capture_string = string.sub(capture_string, 2)
   end
 
-  local best
-  local best_score
+  local best ---@type table|nil
+  local best_score ---@type number
 
   for maybe_match in M.iter_group_results(bufnr, query_group, root) do
     local match = utils.get_at_path(maybe_match, capture_string)
@@ -372,8 +391,8 @@ end
 ---Iterates matches from a query file.
 ---@param bufnr integer the buffer
 ---@param query_group string the query file to use
----@param root LanguageTree the root node
----@param root_lang string|nil the root node lang, if known
+---@param root TSNode the root node
+---@param root_lang? string the root node lang, if known
 function M.iter_group_results(bufnr, query_group, root, root_lang)
   local query, params = prepare_query(bufnr, query_group, root, root_lang)
   if not query then
@@ -396,13 +415,14 @@ end
 
 ---@alias CaptureResFn function(string, LanguageTree, LanguageTree): string, string
 
---- Same as get_capture_matches except this will recursively get matches for every language in the tree.
----@param bufnr integer The bufnr
+-- Same as get_capture_matches except this will recursively get matches for every language in the tree.
+---@param bufnr integer The buffer
 ---@param capture_or_fn string|CaptureResFn The capture to get. If a function is provided then that
----                     function will be used to resolve both the capture and query argument.
----                     The function can return `nil` to ignore that tree.
----@param query_type string The query to get the capture from. This is ignore if a function is provided
----                  for the captuer argument.
+---                       function will be used to resolve both the capture and query argument.
+---                       The function can return `nil` to ignore that tree.
+---@param query_type string? The query to get the capture from. This is ignored if a function is provided
+---                    for the capture argument.
+---@return table[]
 function M.get_capture_matches_recursively(bufnr, capture_or_fn, query_type)
   ---@type CaptureResFn
   local type_fn
@@ -422,7 +442,7 @@ function M.get_capture_matches_recursively(bufnr, capture_or_fn, query_type)
       local capture, type_ = type_fn(lang, tree, lang_tree)
 
       if capture then
-        vim.list_extend(matches, M.get_capture_matches(bufnr, capture, type_, tree:root(), lang))
+        vim.list_extend(matches, M.get_capture_matches(bufnr, capture, type_, tree:root(), lang) or {})
       end
     end)
   end