docs(#3088): add nvim-tree.api* function and class meta, generate help documentation, lazy load api

CONTRIBUTING.md

@@ -139,7 +139,7 @@ This will:
 2. Regenerate from `*nvim-tree-config*` to the end of the file, see `gen_vimdoc.sh`
 3. Update default mappings in `*nvim-tree-mappings-default*` and `*nvim-tree-quickstart-help*`
 
-Commit your changes then run:
+Commit or stage your changes then run:
 ```sh
 make help-check
 ```

Makefile

@@ -12,10 +12,8 @@ check: luals
 #
 # subtasks
 #
-# TODO #3241 ensure that decorator is checked - all meta should be valid
 luacheck:
-	luacheck --codes --quiet lua --exclude-files "**/_meta/api_decorator.lua"
-	luacheck --codes --quiet scripts
+	luacheck --codes --quiet lua --exclude-files "**/_meta/**"
 
 style-check:
 	scripts/luals-check.sh codestyle-check

README.md

@@ -97,7 +97,7 @@ local function my_on_attach(bufnr)
   end
 
   -- default mappings
-  api.config.mappings.default_on_attach(bufnr)
+  api.map.on_attach.default(bufnr)
 
   -- custom mappings
   vim.keymap.set('n', '<C-t>', api.tree.change_root_to_parent,        opts('Up'))

lua/nvim-tree.lua

@@ -1,3 +1,4 @@
+local api = require("nvim-tree.api")
 local log = require("nvim-tree.log")
 local view = require("nvim-tree.view")
 local utils = require("nvim-tree.utils")
@@ -811,6 +812,8 @@ function M.setup(conf)
 
   vim.g.NvimTreeSetup = 1
   vim.api.nvim_exec_autocmds("User", { pattern = "NvimTreeSetup" })
+
+  require("nvim-tree.api.impl.post")(api)
 end
 
 vim.g.NvimTreeRequired = 1

lua/nvim-tree/_meta/api/_git.lua

@@ -0,0 +1,9 @@
+---@meta
+local nvim_tree = { api = { git = {} } }
+
+---
+---Update the git status of the entire tree.
+---
+function nvim_tree.api.git.reload() end
+
+return nvim_tree.api.git

lua/nvim-tree/_meta/api/commands.lua

@@ -0,0 +1,20 @@
+---@meta
+local nvim_tree = { api = { commands = {} } }
+
+---
+---@class nvim_tree.api.commands.Command
+---@inlinedoc
+---
+---@field name string name of the `:NvimTree*` command
+---@field command fun(args: vim.api.keyset.create_user_command.command_args) function that the command will execute
+---@field opts vim.api.keyset.user_command [command-attributes]
+
+---
+---Retrieve all [nvim-tree-commands]
+---
+---They have been created via [nvim_create_user_command()], see also [lua-guide-commands-create]
+---
+---@return nvim_tree.api.commands.Command[]
+function nvim_tree.api.commands.get() end
+
+return nvim_tree.api.commands

lua/nvim-tree/_meta/api/events.lua

@@ -0,0 +1,11 @@
+---@meta
+local nvim_tree = { api = { events = {} } }
+
+---
+---Register a handler for an event, see [nvim-tree-events].
+---
+---@param event_type string [nvim_tree_events_kind]
+---@param callback fun(payload: table?)
+function nvim_tree.api.events.subscribe(event_type, callback) end
+
+return nvim_tree.api.events

lua/nvim-tree/_meta/api/filter.lua

@@ -0,0 +1,61 @@
+---@meta
+local nvim_tree = { api = { filter = {} } }
+
+---
+---Toggle [nvim_tree.config.filters] {enable} which applies to ALL filters.
+---
+function nvim_tree.api.filter.toggle() end
+
+nvim_tree.api.filter.live = {}
+
+---
+---Enter live filter mode. Opens an input window with [filetype] `NvimTreeFilter`
+---
+function nvim_tree.api.filter.live.start() end
+
+---
+---Exit live filter mode.
+---
+function nvim_tree.api.filter.live.clear() end
+
+nvim_tree.api.filter.git = { clean = {}, ignored = {} }
+
+---
+---Toggle [nvim_tree.config.filters] {git_clean} filter.
+---
+function nvim_tree.api.filter.git.clean.toggle() end
+
+---
+---Toggle [nvim_tree.config.filters] {git_ignored} filter.
+---
+function nvim_tree.api.filter.git.ignored.toggle() end
+
+nvim_tree.api.filter.dotfiles = {}
+
+---
+---Toggle [nvim_tree.config.filters] {dotfiles} filter.
+---
+function nvim_tree.api.filter.dotfiles.toggle() end
+
+nvim_tree.api.filter.no_buffer = {}
+
+---
+---Toggle [nvim_tree.config.filters] {no_buffer} filter.
+---
+function nvim_tree.api.filter.no_buffer.toggle() end
+
+nvim_tree.api.filter.no_bookmark = {}
+
+---
+---Toggle [nvim_tree.config.filters] {no_bookmark} filter.
+---
+function nvim_tree.api.filter.no_bookmark.toggle() end
+
+nvim_tree.api.filter.custom = {}
+
+---
+---Toggle [nvim_tree.config.filters] {custom} filter.
+---
+function nvim_tree.api.filter.custom.toggle() end
+
+return nvim_tree.api.filter

lua/nvim-tree/_meta/api/fs.lua

@@ -0,0 +1,114 @@
+---@meta
+local nvim_tree = { api = { fs = {} } }
+
+---
+---Clear the nvim-tree clipboard.
+---
+function nvim_tree.api.fs.clear_clipboard() end
+
+nvim_tree.api.fs.copy = {}
+
+---
+---Copy the absolute path to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.absolute_path(node) end
+
+---
+---Copy the name with extension omitted to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.basename(node) end
+
+---
+---Copy the name to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.filename(node) end
+
+---
+---Copy to the nvim-tree clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.node(node) end
+
+---
+---Copy the path relative to the tree root to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.relative_path(node) end
+
+---
+---Prompt to create a file or directory.
+---
+---When {node} is a file it will be created in the parent directory.
+---
+---Use a trailing `"/"` to create a directory e.g. `"foo/"`
+---
+---Multiple directories/files may be created e.g. `"foo/bar/baz"`
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.create(node) end
+
+---
+---Cut to the nvim-tree clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.cut(node) end
+
+---
+---Paste from the nvim-tree clipboard.
+---
+---If {node} is a file it will pasted in the parent directory.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.paste(node) end
+
+---
+---Print the contents of the nvim-tree clipboard.
+---
+function nvim_tree.api.fs.print_clipboard() end
+
+---
+---Delete from the file system.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.remove(node) end
+
+---
+---Prompt to rename by name.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.rename(node) end
+
+---
+---Prompt to rename by name with extension omitted.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.rename_basename(node) end
+
+---
+---Prompt to rename by absolute path.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.rename_full(node) end
+
+---
+---Prompt to rename.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.rename_node(node) end
+
+---
+---Prompt to rename by absolute path with name omitted.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.rename_sub(node) end
+
+---
+---Trash as per |nvim_tree.config.trash|
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.trash(node) end
+
+return nvim_tree.api.fs

lua/nvim-tree/_meta/api/health.lua

@@ -0,0 +1,11 @@
+---@meta
+local nvim_tree = { api = { health = {} } }
+
+---
+---Open a new buffer displaying all nvim-tree highlight groups, their link chain and concrete definition.
+---
+---Similar to `:so $VIMRUNTIME/syntax/hitest.vim` as per |:highlight|
+---
+function nvim_tree.api.health.hi_test() end
+
+return nvim_tree.api.health

lua/nvim-tree/_meta/api/map.lua

@@ -0,0 +1,26 @@
+---@meta
+local nvim_tree = { api = { map = {} } }
+
+nvim_tree.api.map.keymap = {}
+
+---
+---Retrieve all buffer local mappings for nvim-tree. These are the mappings that are applied by [nvim_tree.config] {on_attach}, which may include default mappings.
+---
+---@return vim.api.keyset.get_keymap[]
+function nvim_tree.api.map.keymap.current() end
+
+---
+--- Retrieves the buffer local mappings for nvim-tree that are applied by [nvim_tree.api.map.on_attach.default()]
+---
+---@return vim.api.keyset.get_keymap[]
+function nvim_tree.api.map.keymap.default() end
+
+nvim_tree.api.map.on_attach = {}
+
+---
+---Apply all [nvim-tree-mappings-default]. Call from your [nvim_tree.config] {on_attach}.
+---
+---@param bufnr integer use the `bufnr` passed to {on_attach}
+function nvim_tree.api.map.on_attach.default(bufnr) end
+
+return nvim_tree.api.map

lua/nvim-tree/_meta/api/marks.lua

@@ -0,0 +1,62 @@
+---@meta
+local nvim_tree = { api = { marks = {} } }
+
+---
+---Return the node if it is marked.
+---
+---@return nvim_tree.api.Node?
+function nvim_tree.api.marks.get() end
+
+---
+---Retrieve all marked nodes.
+---
+---@return nvim_tree.api.Node[]
+function nvim_tree.api.marks.list() end
+
+---
+---Toggle mark.
+---
+---@param node? nvim_tree.api.Node file or directory
+function nvim_tree.api.marks.toggle(node) end
+
+---
+---Clear all marks.
+---
+function nvim_tree.api.marks.clear() end
+
+nvim_tree.api.marks.bulk = {}
+
+---
+---Delete all marked, prompting if [nvim_tree.config.ui.confirm] {remove}
+---
+function nvim_tree.api.marks.bulk.delete() end
+
+---
+---Delete all marked, prompting if [nvim_tree.config.ui.confirm] {trash}
+---
+function nvim_tree.api.marks.bulk.trash() end
+
+---
+---Prompts for a directory to move all marked nodes into.
+---
+function nvim_tree.api.marks.bulk.move() end
+
+nvim_tree.api.marks.navigate = {}
+
+---
+---Navigate to the next marked node, wraps.
+---
+function nvim_tree.api.marks.navigate.next() end
+
+---
+---Navigate to the previous marked node, wraps.
+---
+function nvim_tree.api.marks.navigate.prev() end
+
+---
+---Prompts for selection of a marked node, sorted by absolute paths.
+---A folder will be focused, a file will be opened.
+---
+function nvim_tree.api.marks.navigate.select() end
+
+return nvim_tree.api.marks