style: fill in missing code docs wherever applicable

lua/nvim-treesitter/locals.lua

@@ -20,15 +20,16 @@ function M.iter_locals(bufnr, root)
   return queries.iter_group_results(bufnr, "locals", root)
 end
 
+---@param bufnr integer
+---@return any
 function M.get_locals(bufnr)
   return queries.get_matches(bufnr, "locals")
 end
 
---- Creates unique id for a node based on text and range
--- @param scope: the scope node of the definition
--- @param bufnr: the buffer
--- @param node_text: the node text to use
--- @returns a string id
+-- Creates unique id for a node based on text and range
+---@param scope TSNode: the scope node of the definition
+---@param node_text string: the node text to use
+---@return string: a string id
 function M.get_definition_id(scope, node_text)
   -- Add a valid starting character in case node text doesn't start with a valid one.
   return table.concat({ "k", node_text or "", scope:range() }, "_")
@@ -76,10 +77,13 @@ function M.get_references(bufnr)
   return refs
 end
 
---- Gets a table with all the scopes containing a node
+-- Gets a table with all the scopes containing a node
 -- The order is from most specific to least (bottom up)
+---@param node TSNode
+---@param bufnr integer
+---@return TSNode[]
 function M.get_scope_tree(node, bufnr)
-  local scopes = {}
+  local scopes = {} ---@type TSNode[]
 
   for scope in M.iter_scope_tree(node, bufnr) do
     table.insert(scopes, scope)
@@ -88,7 +92,10 @@ function M.get_scope_tree(node, bufnr)
   return scopes
 end
 
---- Iterates over a nodes scopes moving from the bottom up
+-- Iterates over a nodes scopes moving from the bottom up
+---@param node TSNode
+---@param bufnr integer
+---@return fun(): TSNode|nil
 function M.iter_scope_tree(node, bufnr)
   local last_node = node
   return function()
@@ -105,12 +112,12 @@ function M.iter_scope_tree(node, bufnr)
 end
 
 -- Gets a table of all nodes and their 'kinds' from a locals list
--- @param local_def the local list result
--- @returns a list of node entries
+---@param local_def any: the local list result
+---@return table: a list of node entries
 function M.get_local_nodes(local_def)
   local result = {}
 
-  M.recurse_local_nodes(local_def, function(def, node, kind)
+  M.recurse_local_nodes(local_def, function(def, _node, kind)
     table.insert(result, vim.tbl_extend("keep", { kind = kind }, def))
   end)
 
@@ -123,10 +130,10 @@ end
 -- * The node
 -- * The full definition match `@definition.var.something` -> 'var.something'
 -- * The last definition match `@definition.var.something` -> 'something'
--- @param The locals result
--- @param The accumulator function
--- @param The full match path to append to
--- @param The last match
+---@param local_def any The locals result
+---@param accumulator function The accumulator function
+---@param full_match? string The full match path to append to
+---@param last_match? string The last match
 function M.recurse_local_nodes(local_def, accumulator, full_match, last_match)
   if type(local_def) ~= "table" then
     return
@@ -141,7 +148,7 @@ function M.recurse_local_nodes(local_def, accumulator, full_match, last_match)
   end
 end
 
---- Get a single dimension table to look definition nodes.
+-- Get a single dimension table to look definition nodes.
 -- Keys are generated by using the range of the containing scope and the text of the definition node.
 -- This makes looking up a definition for a given scope a simple key lookup.
 --
@@ -152,8 +159,8 @@ end
 -- Usage lookups require finding the definition of the node, so `find_definition`
 -- is called very frequently, which is why this lookup must be fast as possible.
 --
--- @param bufnr: the buffer
--- @returns a table for looking up definitions
+---@param bufnr integer: the buffer
+---@return table result: a table for looking up definitions
 M.get_definitions_lookup_table = ts_utils.memoize_by_buf_tick(function(bufnr)
   local definitions = M.get_definitions(bufnr)
   local result = {}
@@ -173,19 +180,19 @@ M.get_definitions_lookup_table = ts_utils.memoize_by_buf_tick(function(bufnr)
   return result
 end)
 
---- Gets all the scopes of a definition based on the scope type
+-- Gets all the scopes of a definition based on the scope type
 -- Scope types can be
 --
 -- "parent": Uses the parent of the containing scope, basically, skipping a scope
 -- "global": Uses the top most scope
 -- "local": Uses the containing scope of the definition. This is the default
 --
--- @param node: the definition node
--- @param bufnr: the buffer
--- @param scope_type: the scope type
+---@param node TSNode: the definition node
+---@param bufnr integer: the buffer
+---@param scope_type string: the scope type
 function M.get_definition_scopes(node, bufnr, scope_type)
   local scopes = {}
-  local scope_count = 1
+  local scope_count = 1 ---@type integer|nil
 
   -- Definition is valid for the containing scope
   -- and the containing scope of that scope
@@ -209,6 +216,11 @@ function M.get_definition_scopes(node, bufnr, scope_type)
   return scopes
 end
 
+---@param node TSNode
+---@param bufnr integer
+---@return TSNode node
+---@return TSNode scope
+---@return string|nil kind
 function M.find_definition(node, bufnr)
   local def_lookup = M.get_definitions_lookup_table(bufnr)
   local node_text = ts_query.get_node_text(node, bufnr)
@@ -227,11 +239,11 @@ function M.find_definition(node, bufnr)
 end
 
 -- Finds usages of a node in a given scope.
--- @param node the node to find usages for
--- @param scope_node the node to look within
--- @returns a list of nodes
+---@param node TSNode the node to find usages for
+---@param scope_node TSNode the node to look within
+---@return TSNode[]: a list of nodes
 function M.find_usages(node, scope_node, bufnr)
-  local bufnr = bufnr or api.nvim_get_current_buf()
+  bufnr = bufnr or api.nvim_get_current_buf()
   local node_text = ts_query.get_node_text(node, bufnr)
 
   if not node_text or #node_text < 1 then
@@ -258,6 +270,10 @@ function M.find_usages(node, scope_node, bufnr)
   return usages
 end
 
+---@param node TSNode
+---@param bufnr? integer
+---@param allow_scope? boolean
+---@return TSNode|nil
 function M.containing_scope(node, bufnr, allow_scope)
   local bufnr = bufnr or api.nvim_get_current_buf()
   local allow_scope = allow_scope == nil or allow_scope == true
@@ -284,8 +300,8 @@ function M.nested_scope(node, cursor_pos)
     return
   end
 
-  local row = cursor_pos.row
-  local col = cursor_pos.col
+  local row = cursor_pos.row ---@type integer
+  local col = cursor_pos.col ---@type integer
   local scope = M.containing_scope(node)
 
   for _, child in ipairs(ts_utils.get_named_children(scope)) do
@@ -321,6 +337,8 @@ function M.next_scope(node)
   end
 end
 
+---@param node TSNode
+---@return TSNode|nil
 function M.previous_scope(node)
   local bufnr = api.nvim_get_current_buf()