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

.luacheckrc

@@ -5,6 +5,7 @@ M.self = false
 
 M.ignore = {
   "631",  -- max_line_length
+  "212", -- TODO #3088 make luacheck understand @meta
 }
 
 -- Global objects defined by the C code

Makefile

@@ -43,8 +43,8 @@ help-update:
 # --ignore-blank-lines is used as nightly has removed unnecessary blank lines that stable (0.11.5) currently inserts
 #
 help-check: help-update
-	git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt
 	@scripts/lintdoc.sh
+	git diff --ignore-blank-lines --exit-code doc/nvim-tree-lua.txt
 
 
 .PHONY: all lint style check luacheck style-check style-doc luals style-fix help-update help-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.default_on_attach(bufnr)
 
   -- custom mappings
   vim.keymap.set('n', '<C-t>', api.tree.change_root_to_parent,        opts('Up'))

lua/nvim-tree/_meta/api_decorator.lua

@@ -12,6 +12,11 @@ local nvim_tree = { api = { decorator = {} } }
 ---Names of builtin decorators or your decorator classes. Builtins are ordered lowest to highest priority.
 ---@alias nvim_tree.api.decorator.Name "Git" | "Opened" | "Hidden" | "Modified" | "Bookmarks" | "Diagnostics" | "Copied" | "Cut" | nvim_tree.api.decorator.UserDecorator
 
+---A string for rendering, with optional highlight groups to apply to it
+---@class (exact) nvim_tree.api.HighlightedString
+---@field str string
+---@field hl string[]
+
 ---Custom decorator, see :help nvim-tree-decorators
 ---
 ---@class (exact) nvim_tree.api.decorator.UserDecorator

lua/nvim-tree/_meta/config/actions.lua

@@ -43,7 +43,7 @@ error("Cannot require a meta file")
 
 
 
----Configure [nvim-tree-api.tree.expand_all()] and [nvim-tree-api.node.expand()]
+---Configure [nvim_tree.api.tree.expand_all()] and [nvim_tree.api.node.expand()]
 ---@class nvim_tree.Config.Actions.ExpandAll
 ---
 ---Limit the number of folders being explored when expanding every folder. Avoids hanging Nvim when running this action on very large folders.

lua/nvim-tree/_meta/config/filters.lua

@@ -9,27 +9,27 @@ error("Cannot require a meta file")
 ---
 ---Filters can be set at startup or toggled live via API with default mappings.
 ---
----`I     `{git_ignored}`         `|nvim-tree-api.tree.toggle_gitignore_filter()|
+---`I     `{git_ignored}`         `|nvim_tree.api.tree.toggle_gitignore_filter()|
 ---Ignore files based on `.gitignore`. Requires |nvim_tree.Config.Git|
 ---
----`H     `{dotfiles}`            `|nvim-tree-api.tree.toggle_hidden_filter()|
+---`H     `{dotfiles}`            `|nvim_tree.api.tree.toggle_hidden_filter()|
 ---Filter dotfiles: files/directories starting with a `.`
 ---
----`C     `{git_clean}`           `|nvim-tree-api.tree.toggle_git_clean_filter()|
+---`C     `{git_clean}`           `|nvim_tree.api.tree.toggle_git_clean_filter()|
 ---Filter files with no git status. `.gitignore` files will not be filtered when {git_ignored}, as they are effectively dirty.
 ---
----`B     `{no_buffer}`           `|nvim-tree-api.tree.toggle_no_buffer_filter()|
+---`B     `{no_buffer}`           `|nvim_tree.api.tree.toggle_no_buffer_filter()|
 ---Filter files that have no |buflisted()| buffer. For performance reasons buffer delete/wipe may not be immediately shown. A reload or filesystem event will always result in an update.
 ---
----`M     `{no_bookmark}`         `|nvim-tree-api.tree.toggle_no_bookmark_filter()|
+---`M     `{no_bookmark}`         `|nvim_tree.api.tree.toggle_no_bookmark_filter()|
 ---Filter files that are not bookmarked. Enabling this is not useful as there is no means yet to persist bookmarks.
 ---
----`U     `{custom}`              `|nvim-tree-api.tree.toggle_custom_filter()|
+---`U     `{custom}`              `|nvim_tree.api.tree.toggle_custom_filter()|
 ---Disable specific file/directory names via:
 ---- a list of backslash escaped |vim.regex| strings e.g. `"^\\.git""`
 ---- a function passed the absolute path of the directory.
 ---
----All filters including live filter may be disabled via {enable} and toggled with |nvim-tree-api.tree.toggle_enable_filters()|
+---All filters including live filter may be disabled via {enable} and toggled with |nvim_tree.api.tree.toggle_enable_filters()|
 ---
 ---Files/directories may be {exclude}d from filtering: they will always be shown, overriding {git_ignored}, {dotfiles} and {custom}.
 ---@class nvim_tree.Config.Filters

lua/nvim-tree/actions/tree/find-file.lua

@@ -6,7 +6,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 --- Find file or buffer
----@param opts ApiTreeFindFileOpts|nil|boolean legacy -> opts.buf
+---@param opts nvim_tree.api.tree.find_file.Opts|nil|boolean legacy -> opts.buf
 function M.fn(opts)
   -- legacy arguments
   if type(opts) == "string" then

lua/nvim-tree/actions/tree/modifiers/collapse.lua

@@ -26,7 +26,7 @@ end
 
 ---Collapse a node, root if nil
 ---@param node Node?
----@param opts ApiCollapseOpts
+---@param opts nvim_tree.api.tree.collapse.Opts
 local function collapse(node, opts)
   local explorer = core.get_explorer()
   if not explorer then
@@ -60,7 +60,7 @@ local function collapse(node, opts)
 end
 
 
----@param opts ApiCollapseOpts|boolean|nil legacy -> opts.keep_buffers
+---@param opts nvim_tree.api.tree.collapse.Opts|boolean|nil legacy -> opts.keep_buffers
 function M.all(opts)
   -- legacy arguments
   if type(opts) == "boolean" then
@@ -73,7 +73,7 @@ function M.all(opts)
 end
 
 ---@param node Node
----@param opts ApiCollapseOpts?
+---@param opts nvim_tree.api.tree.collapse.Opts?
 function M.node(node, opts)
   collapse(node, opts or {})
 end

lua/nvim-tree/actions/tree/modifiers/expand.lua

@@ -125,7 +125,7 @@ local function gen_iterator(should_descend)
 end
 
 ---@param node Node?
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts nvim_tree.api.tree.expand.Opts?
 local function expand_node(node, expand_opts)
   if not node then
     return
@@ -141,14 +141,14 @@ end
 
 ---Expand the directory node or the root
 ---@param node Node
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts nvim_tree.api.tree.expand.Opts?
 function M.all(node, expand_opts)
   expand_node(node and node:as(DirectoryNode) or core.get_explorer(), expand_opts)
 end
 
 ---Expand the directory node or parent node
 ---@param node Node
----@param expand_opts ApiTreeExpandOpts?
+---@param expand_opts nvim_tree.api.tree.expand.Opts?
 function M.node(node, expand_opts)
   if not node then
     return

lua/nvim-tree/actions/tree/open.lua

@@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 ---Open the tree, focusing if already open.
----@param opts ApiTreeOpenOpts|nil|string legacy -> opts.path
+---@param opts nvim_tree.api.tree.open.Opts|nil|string legacy -> opts.path
 function M.fn(opts)
   -- legacy arguments
   if type(opts) == "string" then

lua/nvim-tree/actions/tree/resize.lua

@@ -3,7 +3,7 @@ local view = require("nvim-tree.view")
 local M = {}
 
 ---Resize the tree, persisting the new size.
----@param opts ApiTreeResizeOpts|nil
+---@param opts nvim_tree.api.tree.resize.Opts|nil
 function M.fn(opts)
   if opts == nil then
     -- reset to config values

lua/nvim-tree/actions/tree/toggle.lua

@@ -5,7 +5,7 @@ local finders_find_file = require("nvim-tree.actions.finders.find-file")
 local M = {}
 
 ---Toggle the tree.
----@param opts ApiTreeToggleOpts|nil|boolean legacy -> opts.find_file
+---@param opts nvim_tree.api.tree.toggle.Opts|nil|boolean legacy -> opts.find_file
 ---@param no_focus string|nil legacy -> opts.focus
 ---@param cwd boolean|nil legacy -> opts.path
 ---@param bang boolean|nil legacy -> opts.update_root