docs(#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

@@ -252,6 +252,7 @@ local function setup_autocommands(opts)
   })
 end
 
+---@type nvim_tree.Config
 local DEFAULT_OPTS = { -- BEGIN_DEFAULT_OPTS
   on_attach = "default",
   hijack_cursor = false,
@@ -627,7 +628,7 @@ local ACCEPTED_ENUMS = {
   },
 }
 
----@param conf table|nil
+---@param conf? nvim_tree.Config
 local function validate_options(conf)
   local msg
 
@@ -732,7 +733,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.lua

@@ -0,0 +1,137 @@
+---@meta
+error("Cannot require a meta file")
+
+
+---@brief
+---
+---Arguments to pass to [nvim-tree-setup].
+---
+---They can be validated by |lsp| when passed directly e.g.
+---```lua
+---  require("nvim-tree").setup({
+---    hijack_cursor = true,
+---  })
+---```
+---
+---or as a typed variable e.g.
+---```lua
+---  ---@type nvim_tree.Config
+---  local config = {
+---    hijack_cursor = true,
+---  }
+---  require("nvim-tree").setup(config)
+---```
+---
+---When a value is not present/nil, the default will be used.
+
+
+
+---@class nvim_tree.Config
+---
+---Runs when creating the nvim-tree buffer. Use this to set your [nvim-tree-mappings]. When `on_attach` is not a function, [nvim-tree-mappings-default] will be called.
+---@field on_attach? string|(fun(bufnr: integer))
+---
+---Keeps the cursor on the first letter of the filename when moving in the tree.
+---(default: `false`)
+---@field hijack_cursor? boolean
+---
+---Reloads the explorer every time a buffer is written to.
+---(default: `true`)
+---@field auto_reload_on_write? boolean
+---
+---Completely disable [netrw], see [nvim-tree-netrw] for details. It is strongly advised to eagerly disable netrw, due to race conditions at vim startup.
+---(default: `false`)
+---@field disable_netrw? boolean
+---
+---Hijack netrw windows, ignored when `disable_netrw` is `true`
+---(default: `true`)
+---@field hijack_netrw? boolean
+---
+---Opens in place of the unnamed buffer if it's empty.
+---(default: `false`)
+---TODO reinstate this one when formatting is done #2934
+-----@field hijack_unnamed_buffer_when_opening? boolean
+---@field hubwo? boolean
+---
+---Preferred root directories. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot].
+---@field root_dirs? string[]
+---
+---Prefer startup root directory when updating root directory of the tree. Requires [nvim_tree.Config.UpdateFocusedFile.UpdateRoot].
+---(default: `false`)
+---@field prefer_startup_root? boolean
+---
+---Changes the tree root directory on [DirChanged] and refreshes the tree.
+---(default: `false`)
+---@field sync_root_with_cwd? boolean
+---
+---Automatically reloads the tree on [BufEnter] nvim-tree.
+---(default: `false`)
+---@field reload_on_bufenter? boolean
+---
+---Change cwd of nvim-tree to that of new buffer's when opening nvim-tree.
+---(default: `false`)
+---@field respect_buf_cwd? boolean
+---
+---Use [vim.ui.select()] style prompts. Necessary when using a UI prompt decorator such as dressing.nvim or telescope-ui-select.nvim
+---(default: `false`)
+---@field select_prompts? boolean
+---
+---[nvim_tree.Config.Sort]
+---@field sort? nvim_tree.Config.Sort
+---
+---[nvim_tree.Config.View]
+---@field view? nvim_tree.Config.View
+---
+---[nvim_tree.Config.Renderer]
+---@field renderer? nvim_tree.Config.Renderer
+---
+---[nvim_tree.Config.HijackDirectories]
+---@field hijack_directories? nvim_tree.Config.HijackDirectories
+---
+---[nvim_tree.Config.UpdateFocusedFile]
+---@field update_focused_file? nvim_tree.Config.UpdateFocusedFile
+---
+---[nvim_tree.Config.SystemOpen]
+---@field system_open? nvim_tree.Config.SystemOpen
+---
+---[nvim_tree.Config.Git]
+---@field git? nvim_tree.Config.Git
+---
+---[nvim_tree.Config.Diagnostics]
+---@field diagnostics? nvim_tree.Config.Diagnostics
+---
+---[nvim_tree.Config.Modified]
+---@field modified? nvim_tree.Config.Modified
+---
+---[nvim_tree.Config.Filters]
+---@field filters? nvim_tree.Config.Filters
+---
+---[nvim_tree.Config.LiveFilter]
+---@field live_filter? nvim_tree.Config.LiveFilter
+---
+---[nvim_tree.Config.FilesystemWatchers]
+---@field filesystem_watchers? nvim_tree.Config.FilesystemWatchers
+---
+---[nvim_tree.Config.Actions]
+---@field actions? nvim_tree.Config.Actions
+---
+---[nvim_tree.Config.Trash]
+---@field trash? nvim_tree.Config.Trash
+---
+---[nvim_tree.Config.Tab]
+---@field tab? nvim_tree.Config.Tab
+---
+---[nvim_tree.Config.Bookmarks]
+---@field bookmarks? nvim_tree.Config.Bookmarks
+---
+---[nvim_tree.Config.Notify]
+---@field notify? nvim_tree.Config.Notify
+---
+---[nvim_tree.Config.Help]
+---@field help? nvim_tree.Config.Help
+---
+---[nvim_tree.Config.UI]
+---@field ui? nvim_tree.Config.UI
+---
+---[nvim_tree.Config.Log]
+---@field log? nvim_tree.Config.Log

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

@@ -0,0 +1,140 @@
+---@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
+
+
+
+--- 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
+
+
+
+---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.
+---(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[]
+
+
+
+---{file_popup} floating window.
+---
+---{open_win_config} is passed directly to [nvim_open_win()], default:
+---```lua
+---{
+---  col = 1,
+---  row = 1,
+---  relative = "cursor",
+---  border = "shadow",
+---  style = "minimal",
+---}
+---```
+---You shouldn't define {width} and {height} values here. They will be overridden to fit the file_popup content.
+---@class nvim_tree.Config.Actions.FilePopup
+---
+---(default: above)
+---@field open_win_config? vim.api.keyset.win_config
+
+
+
+---Opening files.
+---@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
+
+
+
+---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
+
+
+
+---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[]
+
+
+---Removing files.
+---@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

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

@@ -0,0 +1,16 @@
+---@meta
+error("Cannot require a meta file")
+
+
+---@brief
+---Optionally {persist} bookmarks to a json file:
+---- `true` use default: `stdpath("data") .. "/nvim-tree-bookmarks.json"`
+---- `false` do not persist
+---- `string` absolute path of your choice
+
+
+
+---@class nvim_tree.Config.Bookmarks
+---
+---(default: `false`)
+---@field persist? boolean|string