doc(#2934): add nvim-tree.Config class and nvim-tree.api classes with generated help

CONTRIBUTING.md

@@ -105,6 +105,7 @@ Suppressions are permitted only in the following cases:
 - Backwards compatibility shims
 - neovim API metadata incorrect, awaiting upstream fix
 - classic class framework
+- `gen_vimdoc_config.lua` help generator as it requires neovim source
 
 # Backwards Compatibility
 

lua/nvim-tree.lua

@@ -621,7 +621,7 @@ local ACCEPTED_ENUMS = {
   },
 }
 
----@param conf table|nil
+---@param conf? nvim_tree.Config
 local function validate_options(conf)
   local msg
 
@@ -726,7 +726,7 @@ function M.purge_all_state()
   require("nvim-tree.watcher").purge_watchers()
 end
 
----@param conf table|nil
+---@param conf? nvim_tree.Config
 function M.setup(conf)
   if vim.fn.has("nvim-0.9") == 0 then
     notify.warn("nvim-tree.lua requires Neovim 0.9 or higher")

lua/nvim-tree/_meta/api.lua

@@ -1,6 +1,59 @@
 ---@meta
 error("Cannot require a meta file")
 
+--
+-- API Options
+--
+
+---@class (exact) nvim_tree.api.TreeOpenOpts
+---@field path? string root directory for the tree
+---@field current_window? boolean open the tree in the current window
+---@field winid? number open the tree in the specified winid, overrides current_window
+---@field find_file? boolean find the current buffer
+---@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root|
+---@field focus? boolean focus the tree when opening, default true
+
+---@class (exact) nvim_tree.api.TreeToggleOpts
+---@field path? string root directory for the tree
+---@field current_window? boolean open the tree in the current window
+---@field winid? number open the tree in the specified |winid|, overrides current_window
+---@field find_file? boolean find the current buffer
+---@field update_root? boolean requires find_file, see |nvim-tree.update_focused_file.update_root|
+---@field focus? boolean focus the tree when opening, default true
+
+---@class (exact) nvim_tree.api.TreeResizeOpts
+---@field width? string|function|number|table new |nvim-tree.view.width| value
+---@field absolute? number set the width
+---@field relative? number relative width adjustment
+
+---@class (exact) nvim_tree.api.TreeFindFileOpts
+---@field buf? string|number absolute/relative path OR bufnr to find
+---@field open? boolean open the tree if necessary
+---@field current_window? boolean requires open, open in the current window
+---@field winid? number open the tree in the specified |winid|, overrides current_window
+---@field update_root? boolean see |nvim-tree.update_focused_file.update_root|
+---@field focus? boolean focus the tree
+
+---@class (exact) nvim_tree.api.CollapseOpts
+---@field keep_buffers? boolean do not collapse nodes with open buffers
+
+---@class (exact) nvim_tree.api.TreeExpandOpts
+---@field expand_until? (fun(expansion_count: integer, node: Node): boolean) Return true if node should be expanded. expansion_count is the total number of folders expanded.
+
+---@class (exact) nvim_tree.api.TreeIsVisibleOpts
+---@field tabpage? number as per |nvim_get_current_tabpage()|
+---@field any_tabpage? boolean visible on any tab, default false
+
+---@class (exact) nvim_tree.api.TreeWinIdOpts
+---@field tabpage? number tabpage, 0 or nil for current, default nil
+
+---@class (exact) nvim_tree.api.NodeEditOpts
+---@field quit_on_open? boolean quits the tree when opening the file
+---@field focus? boolean keep focus in the tree when opening the file
+
+---@class (exact) nvim_tree.api.NodeBufferOpts
+---@field force? boolean delete/wipe even if buffer is modified, default false
+
 --
 -- Nodes
 --

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

@@ -0,0 +1,144 @@
+---@meta
+error("Cannot require a meta file")
+
+---@class nvim_tree.Config.Actions
+---
+---Use the system clipboard for copy/paste. Copied text will be stored in registers `+` (system), otherwise, it will be stored in `1` and `"`
+---(default: `true`)
+---@field use_system_clipboard? boolean
+---
+---|nvim_tree.Config.Actions.ChangeDir|
+---@field change_dir? nvim_tree.Config.Actions.ChangeDir
+---
+---|nvim_tree.Config.Actions.ExpandAll|
+---@field expand_all? nvim_tree.Config.Actions.ExpandAll
+---
+---|nvim_tree.Config.Actions.FilePopup|
+---@field file_popup? nvim_tree.Config.Actions.FilePopup
+---
+---|nvim_tree.Config.Actions.OpenFile|
+---@field open_file? nvim_tree.Config.Actions.OpenFile
+---
+---|nvim_tree.Config.Actions.RemoveFile|
+---@field remove_file? nvim_tree.Config.Actions.RemoveFile
+
+--
+-- Actions.ChangeDir
+--
+
+--- vim |current-directory| behaviour
+---@class nvim_tree.Config.Actions.ChangeDir
+---
+---Change the working directory when changing directories in the tree
+---(default: `true`)
+---@field enable? boolean
+---
+---Use `:cd` instead of `:lcd` when changing directories.
+---(default: `false`)
+---@field global? boolean
+---
+--- Restrict changing to a directory above the global cwd.
+---(default: `false`)
+---@field restrict_above_cwd? boolean
+
+--
+-- Actions.ExpandAll
+--
+
+---Configuration for |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 folders. Avoids hanging neovim when running this action on very large folders.
+---(default: `300`)
+---@field max_folder_discovery? integer
+---
+---A list of directories that should not be expanded automatically e.g `{ ".git", "target", "build" }`
+---(default: `{}`)
+---@field exclude? string[]
+
+--
+-- Actions.FilePopup
+--
+
+---Configuration for file_popup floating window, see |nvim_open_win|
+---
+---You shouldn't define |vim.api.keyset.win_config| {width} and {height} values here. They will be overridden to fit the file_popup content.
+---@class nvim_tree.Config.Actions.FilePopup
+---
+---Neovim window config.
+---(default: `{ col = 1, row = 1, relative = "cursor", border = "shadow", style = "minimal", }`)
+---@field open_win_config? vim.api.keyset.win_config
+
+--
+-- Actions.OpenFile
+--
+
+---Configuration options for opening a file from nvim-tree.
+---@class nvim_tree.Config.Actions.OpenFile
+---
+---Closes the explorer when opening a file
+---(default: `false`)
+---@field quit_on_open? boolean
+---
+---Prevent new opened file from opening in the same window as the tree.
+---(default: `true`)
+---@field eject? boolean
+---
+---Resizes the tree when opening a file
+---(default: `true`)
+---@field resize_window? boolean
+---
+---|nvim_tree.Config.Actions.OpenFile.WindowPicker|
+---@field window_picker? nvim_tree.Config.Actions.OpenFile.WindowPicker
+
+--
+-- Actions.OpenFile.WindowPicker
+--
+
+---A window picker will be shown when there are multiple windows available to open a file. It will show a single character identifier in each window's status line.
+---
+---When it is not enabled the file will open in the window from which you last opened the tree, obeying {exclude}
+---
+---You may define a function that should return the window id that will open the node, or `nil` if an invalid window is picked or user cancelled the action. The picker may create a new window.
+---
+---@class nvim_tree.Config.Actions.OpenFile.WindowPicker
+---
+---(default: `true`)
+---@field enable? boolean
+---
+---Change the default window picker: string `default` or a function.
+---(default: `default`)
+---@field picker? string|fun(): integer
+---
+---Identifier characters to use.
+---(default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`)
+---@field chars? string
+---
+---|nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude|
+---@field exclude? nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude
+
+--
+-- Actions.OpenFile.WindowPicker.Exclude
+--
+
+---Tables of buffer option names mapped to a list of option values. Windows containing matching buffers will not be:
+--- - available when using a window picker
+--- - selected when not using a window picker
+---@class nvim_tree.Config.Actions.OpenFile.WindowPicker.Exclude
+---
+---(default: `{ "notify", "lazy", "qf", "diff", "fugitive", "fugitiveblame", }`)
+---@field filetype? string[]
+---
+---(default: `{ "nofile", "terminal", "help", }`)
+---@field buftype? string[]
+
+--
+-- Actions.RemoveFile
+--
+
+---Configuration options for removing a file from nvim-tree.
+---@class nvim_tree.Config.Actions.RemoveFile
+---
+---Close any window that displays a file when removing that file from the tree.
+---(default: `true`)
+---@field close_window? boolean