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

.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.

.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

.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",

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)

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 = ""

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)

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

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

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)

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,