style: fill in missing code docs wherever applicable

lua/nvim-treesitter/utils.lua

@@ -5,12 +5,15 @@ local luv = vim.loop
 local M = {}
 
 -- Wrapper around vim.notify with common options set.
+---@param msg string
+---@param log_level number|nil
+---@param opts table|nil
 function M.notify(msg, log_level, opts)
   local default_opts = { title = "nvim-treesitter" }
   vim.notify(msg, log_level, vim.tbl_extend("force", default_opts, opts or {}))
 end
 
--- Returns the system specific path separator.
+-- Returns the system-specific path separator.
 ---@return string
 function M.get_path_sep()
   return (fn.has "win32" == 1 and not vim.opt.shellslash:get()) and "\\" or "/"
@@ -18,10 +21,13 @@ end
 
 -- Returns a function that joins the given arguments with separator. Arguments
 -- can't be nil. Example:
+--
 --[[
-print(M.generate_join(" ")("foo", "bar"))
+  print(M.generate_join(" ")("foo", "bar"))
 --]]
--- prints "foo bar"
+--prints "foo bar"
+---@param separator string
+---@return fun(...: string): string
 function M.generate_join(separator)
   return function(...)
     return table.concat({ ... }, separator)
@@ -32,13 +38,18 @@ M.join_path = M.generate_join(M.get_path_sep())
 
 M.join_space = M.generate_join " "
 
---- Define user defined vim command which calls nvim-treesitter module function
----     - If module name is 'mod', it should be defined in hierarchy 'nvim-treesitter.mod'
----     - A table with name 'commands' should be defined in 'mod' which needs to be passed as
----       the commands param of this function
----
----@param mod string, Name of the module that resides in the hierarchy - nvim-treesitter.module
----@param commands table, Command list for the module
+---@class Command
+---@field run function
+---@field f_args string
+---@field args string
+
+-- Define user defined vim command which calls nvim-treesitter module function
+--     - If module name is 'mod', it should be defined in hierarchy 'nvim-treesitter.mod'
+--     - A table with name 'commands' should be defined in 'mod' which needs to be passed as
+--       the commands param of this function
+--
+---@param mod string  Name of the module that resides in the hierarchy - nvim-treesitter.module
+---@param commands table<string, Command>  Command list for the module
 ---         - {command_name} Name of the vim user defined command, Keys:
 ---             - {run}: (function) callback function that needs to be executed
 ---             - {f_args}: (string, default <f-args>)
@@ -46,7 +57,7 @@ M.join_space = M.generate_join " "
 ---             - {args}: (string, optional)
 ---                 - vim command attributes
 ---
----Example:
+---* @example
 ---  If module is nvim-treesitter.custom_mod
 ---  <pre>
 ---  M.commands = {
@@ -136,18 +147,22 @@ function M.get_site_dir()
 end
 
 -- Gets a property at path
--- @param tbl the table to access
--- @param path the '.' separated path
--- @returns the value at path or nil
+---@param tbl table the table to access
+---@param path string the '.' separated path
+---@return table|nil result the value at path or nil
 function M.get_at_path(tbl, path)
   if path == "" then
     return tbl
   end
+
   local segments = vim.split(path, ".", true)
+  ---@type table[]|table
   local result = tbl
 
   for _, segment in ipairs(segments) do
     if type(result) == "table" then
+      ---@type table
+      -- TODO: figure out the actual type of tbl
       result = result[segment]
     end
   end
@@ -159,17 +174,9 @@ function M.set_jump()
   vim.cmd "normal! m'"
 end
 
-function M.index_of(tbl, obj)
-  for i, o in ipairs(tbl) do
-    if o == obj then
-      return i
-    end
-  end
-end
-
 -- Filters a list based on the given predicate
--- @param tbl The list to filter
--- @param predicate The predicate to filter with
+---@param tbl any[] The list to filter
+---@param predicate fun(v:any, i:number):boolean The predicate to filter with
 function M.filter(tbl, predicate)
   local result = {}
 
@@ -184,8 +191,9 @@ end
 
 -- Returns a list of all values from the first list
 -- that are not present in the second list.
--- @params tbl1 The first table
--- @params tbl2 The second table
+---@param tbl1 any[] The first table
+---@param tbl2 any[] The second table
+---@return table
 function M.difference(tbl1, tbl2)
   return M.filter(tbl1, function(v)
     return not vim.tbl_contains(tbl2, v)
@@ -196,12 +204,19 @@ function M.identity(a)
   return a
 end
 
+-- Returns a function returning the given value
+---@param a any
+---@return fun():any
 function M.constant(a)
   return function()
     return a
   end
 end
 
+-- Returns a function that returns the given value if it is a function,
+-- otherwise returns a function that returns the given value.
+---@param a any
+---@return fun(...):any
 function M.to_func(a)
   return type(a) == "function" and a or M.constant(a)
 end
@@ -209,7 +224,10 @@ end
 ---@return string|nil
 function M.ts_cli_version()
   if fn.executable "tree-sitter" == 1 then
-    local handle = io.popen "tree-sitter  -V"
+    local handle = io.popen "tree-sitter -V"
+    if not handle then
+      return
+    end
     local result = handle:read "*a"
     handle:close()
     return vim.split(result, "\n")[1]:match "[^tree%psitter ].*"