chore: enable incomplete-signature-doc, format nvt-min.lua, assorted formatting tidies (#2967)

* chore: luacheckrc uses table

* chore: format nvt-min.lua

* chore: complete lua doc

* chore: complete lua doc

* chore: complete lua doc

* chore: complete lua doc

* chore: complete lua doc

* chore: enable incomplete-signature-doc

* chore: enable incomplete-signature-doc

* chore: complete lua doc

* chore: complete lua doc

Author: alex-courtis

Diff for: .github/ISSUE_TEMPLATE/nvt-min.lua

@@ -1,12 +1,12 @@
 vim.g.loaded_netrw = 1
 vim.g.loaded_netrwPlugin = 1
 
-vim.cmd [[set runtimepath=$VIMRUNTIME]]
-vim.cmd [[set packpath=/tmp/nvt-min/site]]
+vim.cmd([[set runtimepath=$VIMRUNTIME]])
+vim.cmd([[set packpath=/tmp/nvt-min/site]])
 local package_root = "/tmp/nvt-min/site/pack"
 local install_path = package_root .. "/packer/start/packer.nvim"
 local function load_plugins()
-  require("packer").startup {
+  require("packer").startup({
     {
       "wbthomason/packer.nvim",
       "nvim-tree/nvim-tree.lua",
@@ -18,21 +18,21 @@ local function load_plugins()
       compile_path = install_path .. "/plugin/packer_compiled.lua",
       display = { non_interactive = true },
     },
-  }
+  })
 end
 if vim.fn.isdirectory(install_path) == 0 then
-  print "Installing nvim-tree and dependencies."
-  vim.fn.system { "git", "clone", "--depth=1", "https://github.com/wbthomason/packer.nvim", install_path }
+  print("Installing nvim-tree and dependencies.")
+  vim.fn.system({ "git", "clone", "--depth=1", "https://github.com/wbthomason/packer.nvim", install_path })
 end
 load_plugins()
 require("packer").sync()
-vim.cmd [[autocmd User PackerComplete ++once echo "Ready!" | lua setup()]]
+vim.cmd([[autocmd User PackerComplete ++once echo "Ready!" | lua setup()]])
 vim.opt.termguicolors = true
 vim.opt.cursorline = true
 
 -- MODIFY NVIM-TREE SETTINGS THAT ARE _NECESSARY_ FOR REPRODUCING THE ISSUE
 _G.setup = function()
-  require("nvim-tree").setup {}
+  require("nvim-tree").setup({})
 end
 
 -- UNCOMMENT this block for diagnostics issues, substituting pattern and cmd as appropriate.

Diff for: .luacheckrc

@@ -1,14 +1,15 @@
--- vim: ft=lua tw=80
+local M = {}
 
 -- Don't report unused self arguments of methods.
-self = false
+M.self = false
 
-ignore = {
+M.ignore = {
   "631",  -- max_line_length
 }
 
 -- Global objects defined by the C code
-globals = {
+M.globals = {
   "vim",
-  "TreeExplorer"
 }
+
+return M

Diff for: .luarc.json

@@ -33,7 +33,7 @@
       "empty-block": "Any",
       "global-element": "Any",
       "global-in-nil-env": "Any",
-      "incomplete-signature-doc": "None",
+      "incomplete-signature-doc": "Any",
       "inject-field": "Any",
       "invisible": "Any",
       "lowercase-global": "Any",

Diff for: lua/nvim-tree/actions/moves/parent.lua

@@ -25,7 +25,8 @@ function M.fn(should_close)
     local parent = (node:get_parent_of_group() or node).parent
 
     if not parent or not parent.parent then
-      return view.set_cursor({ 1, 0 })
+      view.set_cursor({ 1, 0 })
+      return
     end
 
     local _, line = utils.find_node(parent.explorer.nodes, function(n)

Diff for: lua/nvim-tree/actions/node/open-file.lua

@@ -369,6 +369,7 @@ end
 
 ---@param mode string
 ---@param filename string
+---@return nil
 function M.fn(mode, filename)
   if type(mode) ~= "string" then
     mode = ""

Diff for: lua/nvim-tree/actions/tree/modifiers/expand-all.lua

@@ -30,15 +30,18 @@ end
 ---@param node Node
 ---@return boolean
 local function should_expand(expansion_count, node)
+  local dir = node:as(DirectoryNode)
+  if not dir then
+    return false
+  end
   local should_halt = expansion_count >= M.MAX_FOLDER_DISCOVERY
-  local should_exclude = M.EXCLUDE[node.name]
-  return not should_halt and node.nodes and not node.open and not should_exclude
+  local should_exclude = M.EXCLUDE[dir.name]
+  return not should_halt and not dir.open and not should_exclude
 end
 
 local function gen_iterator()
   local expansion_count = 0
 
-  ---@param parent DirectoryNode
   return function(parent)
     if parent.parent and parent.nodes and not parent.open then
       expansion_count = expansion_count + 1
@@ -47,14 +50,15 @@ local function gen_iterator()
 
     Iterator.builder(parent.nodes)
       :hidden()
-    ---@param node DirectoryNode
       :applier(function(node)
         if should_expand(expansion_count, node) then
           expansion_count = expansion_count + 1
-          expand(node)
+          node = node:as(DirectoryNode)
+          if node then
+            expand(node)
+          end
         end
       end)
-    ---@param node DirectoryNode
       :recursor(function(node)
         return expansion_count < M.MAX_FOLDER_DISCOVERY and (node.group_next and { node.group_next } or (node.open and node.nodes))
       end)

Diff for: lua/nvim-tree/api.lua

@@ -42,21 +42,21 @@ local Api = {
 }
 
 --- Print error when setup not called.
---- f function to invoke
----@param f function
----@return fun(...) : any
-local function wrap(f)
+---@param fn fun(...): any
+---@return fun(...): any
+local function wrap(fn)
   return function(...)
     if vim.g.NvimTreeSetup == 1 then
-      return f(...)
+      return fn(...)
     else
       notify.error("nvim-tree setup not called")
     end
   end
 end
 
 ---Inject the node as the first argument if present otherwise do nothing.
----@param fn function function to invoke
+---@param fn fun(node: Node, ...): any
+---@return fun(node: Node, ...): any
 local function wrap_node(fn)
   return function(node, ...)
     node = node or lib.get_node_at_cursor()
@@ -67,7 +67,8 @@ local function wrap_node(fn)
 end
 
 ---Inject the node or nil as the first argument if absent.
----@param fn function function to invoke
+---@param fn fun(node: Node, ...): any
+---@return fun(node: Node, ...): any
 local function wrap_node_or_nil(fn)
   return function(node, ...)
     node = node or lib.get_node_at_cursor()
@@ -78,7 +79,7 @@ end
 ---Invoke a method on the singleton explorer.
 ---Print error when setup not called.
 ---@param explorer_method string explorer method name
----@return fun(...) : any
+---@return fun(...): any
 local function wrap_explorer(explorer_method)
   return wrap(function(...)
     local explorer = core.get_explorer()
@@ -92,7 +93,7 @@ end
 ---Print error when setup not called.
 ---@param explorer_member string explorer member name
 ---@param member_method string method name to invoke on member
----@return fun(...) : any
+---@return fun(...): any
 local function wrap_explorer_member(explorer_member, member_method)
   return wrap(function(...)
     local explorer = core.get_explorer()
@@ -211,6 +212,7 @@ local function edit(mode, node)
 end
 
 ---@param mode string
+---@param toggle_group boolean?
 ---@return fun(node: Node)
 local function open_or_expand_or_dir_up(mode, toggle_group)
   ---@param node Node

Diff for: lua/nvim-tree/explorer/filters.lua

@@ -107,9 +107,11 @@ local function dotfile(self, path)
   return self.config.filter_dotfiles and utils.path_basename(path):sub(1, 1) == "."
 end
 
+---Bookmark is present
 ---@param path string
 ---@param path_type string|nil filetype of path
 ---@param bookmarks table<string, string|nil> path, filetype table of bookmarked files
+---@return boolean
 local function bookmark(self, path, path_type, bookmarks)
   if not self.config.filter_no_bookmark then
     return false

Diff for: lua/nvim-tree/explorer/init.lua

@@ -80,6 +80,7 @@ end
 
 ---@param node DirectoryNode
 ---@param git_status table|nil
+---@return Node[]?
 function Explorer:reload(node, git_status)
   local cwd = node.link_to or node.absolute_path
   local handle = vim.loop.fs_scandir(cwd)

Diff for: lua/nvim-tree/explorer/live-filter.lua

@@ -13,6 +13,7 @@ local LiveFilter = {}
 
 ---@param opts table
 ---@param explorer Explorer
+---@return LiveFilter
 function LiveFilter:new(opts, explorer)
   local o = {
     explorer = explorer,

Diff for: lua/nvim-tree/explorer/sorters.lua

@@ -17,7 +17,7 @@ end
 
 --- Predefined comparator, defaulting to name
 ---@param sorter string as per options
----@return function
+---@return fun(a: Node, b: Node): boolean
 function Sorter:get_comparator(sorter)
   return function(a, b)
     return (C[sorter] or C.name)(a, b, self.config)
@@ -41,6 +41,7 @@ end
 ---Evaluate `sort.folders_first` and `sort.files_first`
 ---@param a Node
 ---@param b Node
+---@param cfg table
 ---@return boolean|nil
 local function folders_or_files_first(a, b, cfg)
   if not (cfg.folders_first or cfg.files_first) then
@@ -164,6 +165,7 @@ end
 ---@param a Node
 ---@param b Node
 ---@param ignorecase boolean|nil
+---@param cfg table
 ---@return boolean
 local function node_comparator_name_ignorecase_or_not(a, b, ignorecase, cfg)
   if not (a and b) then

Diff for: lua/nvim-tree/help.lua

@@ -53,6 +53,7 @@ end
 --- sort vim command lhs roughly as per :help index
 ---@param a string
 ---@param b string
+---@return boolean
 local function sort_lhs(a, b)
   -- mouse first
   if a:match(PAT_MOUSE) and not b:match(PAT_MOUSE) then

Diff for: lua/nvim-tree/keymap.lua

@@ -1,7 +1,7 @@
 local M = {}
 
 --- Apply mappings to a scratch buffer and return buffer local mappings
----@param fn function(bufnr) on_attach or default_on_attach
+---@param fn fun(bufnr: integer) on_attach or default_on_attach
 ---@return table as per vim.api.nvim_buf_get_keymap
 local function generate_keymap(fn)
   -- create an unlisted scratch buffer

Diff for: lua/nvim-tree/log.lua

@@ -92,7 +92,7 @@ end
 ---@param typ string as per log.types config
 ---@param node Node? node to be inspected
 ---@param fmt string for string.format
----@vararg any arguments for string.format
+---@param ... any arguments for string.format
 function M.node(typ, node, fmt, ...)
   if M.enabled(typ) then
     node = node or require("nvim-tree.lib").get_node_at_cursor()

Diff for: lua/nvim-tree/renderer/components/padding.lua

@@ -61,6 +61,7 @@ end
 ---@param nodes_number integer
 ---@param node Node
 ---@param markers table
+---@param early_stop integer?
 ---@return HighlightedString[]
 function M.get_indent_markers(depth, idx, nodes_number, node, markers, early_stop)
   local str = ""

Diff for: lua/nvim-tree/renderer/init.lua

@@ -41,6 +41,8 @@ end
 ---@param lines string[]
 ---@param hl_args AddHighlightArgs[]
 ---@param signs string[]
+---@param extmarks table[] extra marks for right icon placement
+---@param virtual_lines table[] virtual lines for hidden count display
 function Renderer:_draw(bufnr, lines, hl_args, signs, extmarks, virtual_lines)
   if vim.fn.has("nvim-0.10") == 1 then
     vim.api.nvim_set_option_value("modifiable", true, { buf = bufnr })

Diff for: lua/nvim-tree/view.lua

@@ -124,6 +124,7 @@ local function get_size(size)
 end
 
 ---@param size (fun():integer)|integer|nil
+---@return integer
 local function get_width(size)
   if size then
     return get_size(size)
@@ -411,6 +412,7 @@ function M.abandon_all_windows()
 end
 
 ---@param opts table|nil
+---@return boolean
 function M.is_visible(opts)
   if opts and opts.tabpage then
     if M.View.tabpages[opts.tabpage] == nil then