docs(#2934): revert API opts classes changes

Author: alex-courtis

lua/nvim-tree/_meta/api.lua

@@ -1,59 +1,6 @@
 ---@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/actions/node/buffer.lua

@@ -4,14 +4,14 @@ local notify = require("nvim-tree.notify")
 local M = {}
 
 ---@param node Node
----@param opts nvim_tree.api.NodeBufferOpts|nil
+---@param opts ApiNodeDeleteWipeBufferOpts|nil
 ---@return nil
 function M.delete(node, opts)
   M.delete_buffer("delete", node.absolute_path, opts)
 end
 
 ---@param node Node
----@param opts nvim_tree.api.NodeBufferOpts|nil
+---@param opts ApiNodeDeleteWipeBufferOpts|nil
 ---@return nil
 function M.wipe(node, opts)
   M.delete_buffer("wipe", node.absolute_path, opts)
@@ -21,7 +21,7 @@ end
 
 ---@param mode ApiNodeDeleteWipeBufferMode
 ---@param filename string
----@param opts nvim_tree.api.NodeBufferOpts|nil
+---@param opts ApiNodeDeleteWipeBufferOpts|nil
 ---@return nil
 function M.delete_buffer(mode, filename, opts)
   if type(mode) ~= "string" then

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 nvim_tree.api.TreeFindFileOpts|nil|boolean legacy -> opts.buf
+---@param opts ApiTreeFindFileOpts|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 nvim_tree.api.CollapseOpts
+---@param opts ApiCollapseOpts
 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 nvim_tree.api.CollapseOpts|boolean|nil legacy -> opts.keep_buffers
+---@param opts ApiCollapseOpts|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 nvim_tree.api.CollapseOpts?
+---@param opts ApiCollapseOpts?
 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 nvim_tree.api.TreeExpandOpts?
+---@param expand_opts ApiTreeExpandOpts?
 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 nvim_tree.api.TreeExpandOpts?
+---@param expand_opts ApiTreeExpandOpts?
 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 nvim_tree.api.TreeExpandOpts?
+---@param expand_opts ApiTreeExpandOpts?
 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 nvim_tree.api.TreeOpenOpts|nil|string legacy -> opts.path
+---@param opts ApiTreeOpenOpts|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 nvim_tree.api.TreeResizeOpts|nil
+---@param opts ApiTreeResizeOpts|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 nvim_tree.api.TreeToggleOpts|nil|boolean legacy -> opts.find_file
+---@param opts ApiTreeToggleOpts|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

lua/nvim-tree/api.lua

@@ -14,18 +14,6 @@ local FileLinkNode = require("nvim-tree.node.file-link")
 local RootNode = require("nvim-tree.node.root")
 local UserDecorator = require("nvim-tree.renderer.decorator.user")
 
--- Backwards compatibility aliases for renamed classes
----@alias ApiTreeOpenOpts nvim_tree.api.TreeOpenOpts
----@alias ApiTreeToggleOpts nvim_tree.api.TreeToggleOpts
----@alias ApiTreeResizeOpts nvim_tree.api.TreeResizeOpts
----@alias ApiTreeFindFileOpts nvim_tree.api.TreeFindFileOpts
----@alias ApiCollapseOpts nvim_tree.api.CollapseOpts
----@alias ApiTreeExpandOpts nvim_tree.api.TreeExpandOpts
----@alias ApiTreeIsVisibleOpts nvim_tree.api.TreeIsVisibleOpts
----@alias ApiTreeWinIdOpts nvim_tree.api.TreeWinIdOpts
----@alias NodeEditOpts nvim_tree.api.NodeEditOpts
----@alias ApiNodeDeleteWipeBufferOpts nvim_tree.api.NodeBufferOpts
-
 local Api = {
   tree = {},
   node = {
@@ -135,15 +123,35 @@ local function wrap_explorer_member(explorer_member, member_method)
   end)
 end
 
+---@class ApiTreeOpenOpts
+---@field path string|nil path
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field find_file boolean|nil default false
+---@field update_root boolean|nil default false
+
 Api.tree.open = wrap(actions.tree.open.fn)
 Api.tree.focus = Api.tree.open
 
+---@class ApiTreeToggleOpts
+---@field path string|nil
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field find_file boolean|nil default false
+---@field update_root boolean|nil default false
+---@field focus boolean|nil default true
+
 Api.tree.toggle = wrap(actions.tree.toggle.fn)
 Api.tree.close = wrap(view.close)
 Api.tree.close_in_this_tab = wrap(view.close_this_tab_only)
 Api.tree.close_in_all_tabs = wrap(view.close_all_tabs)
 Api.tree.reload = wrap_explorer("reload_explorer")
 
+---@class ApiTreeResizeOpts
+---@field width string|function|number|table|nil
+---@field absolute number|nil
+---@field relative number|nil
+
 Api.tree.resize = wrap(actions.tree.resize.fn)
 
 Api.tree.change_root = wrap(function(...)
@@ -171,11 +179,25 @@ Api.tree.change_root_to_parent = wrap_node(wrap_explorer("dir_up"))
 Api.tree.get_node_under_cursor = wrap_explorer("get_node_at_cursor")
 Api.tree.get_nodes = wrap_explorer("get_nodes")
 
+---@class ApiTreeFindFileOpts
+---@field buf string|number|nil
+---@field open boolean|nil default false
+---@field current_window boolean|nil default false
+---@field winid number|nil
+---@field update_root boolean|nil default false
+---@field focus boolean|nil default false
+
 Api.tree.find_file = wrap(actions.tree.find_file.fn)
 Api.tree.search_node = wrap(actions.finders.search_node.fn)
 
+---@class ApiCollapseOpts
+---@field keep_buffers boolean|nil default false
+
 Api.tree.collapse_all = wrap(actions.tree.modifiers.collapse.all)
 
+---@class ApiTreeExpandOpts
+---@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil
+
 Api.tree.expand_all = wrap_node(actions.tree.modifiers.expand.all)
 Api.tree.toggle_enable_filters = wrap_explorer_member("filters", "toggle")
 Api.tree.toggle_gitignore_filter = wrap_explorer_member_args("filters", "toggle", "git_ignored")
@@ -187,8 +209,15 @@ Api.tree.toggle_no_bookmark_filter = wrap_explorer_member_args("filters", "toggl
 Api.tree.toggle_help = wrap(help.toggle)
 Api.tree.is_tree_buf = wrap(utils.is_nvim_tree_buf)
 
+---@class ApiTreeIsVisibleOpts
+---@field tabpage number|nil
+---@field any_tabpage boolean|nil default false
+
 Api.tree.is_visible = wrap(view.is_visible)
 
+---@class ApiTreeWinIdOpts
+---@field tabpage number|nil default nil
+
 Api.tree.winid = wrap(view.winid)
 
 Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
@@ -209,9 +238,13 @@ Api.fs.copy.filename = wrap_node(wrap_explorer_member("clipboard", "copy_filenam
 Api.fs.copy.basename = wrap_node(wrap_explorer_member("clipboard", "copy_basename"))
 Api.fs.copy.relative_path = wrap_node(wrap_explorer_member("clipboard", "copy_path"))
 ---
+---@class NodeEditOpts
+---@field quit_on_open boolean|nil default false
+---@field focus boolean|nil default true
+
 ---@param mode string
 ---@param node Node
----@param edit_opts nvim_tree.api.NodeEditOpts?
+---@param edit_opts NodeEditOpts?
 local function edit(mode, node, edit_opts)
   local file_link = node:as(FileLinkNode)
   local path = file_link and file_link.link_to or node.absolute_path
@@ -239,10 +272,10 @@ end
 
 ---@param mode string
 ---@param toggle_group boolean?
----@return fun(node: Node, edit_opts: nvim_tree.api.NodeEditOpts?)
+---@return fun(node: Node, edit_opts: NodeEditOpts?)
 local function open_or_expand_or_dir_up(mode, toggle_group)
   ---@param node Node
-  ---@param edit_opts nvim_tree.api.NodeEditOpts?
+  ---@param edit_opts NodeEditOpts?
   return function(node, edit_opts)
     local root = node:as(RootNode)
     local dir = node:as(DirectoryNode)
@@ -297,6 +330,9 @@ Api.node.navigate.opened.prev = wrap_node(actions.moves.item.fn({ where = "prev"
 Api.node.expand = wrap_node(actions.tree.modifiers.expand.node)
 Api.node.collapse = wrap_node(actions.tree.modifiers.collapse.node)
 
+---@class ApiNodeDeleteWipeBufferOpts
+---@field force boolean|nil default false
+
 Api.node.buffer.delete = wrap_node(function(node, opts)
   actions.node.buffer.delete(node, opts)
 end)

lua/nvim-tree/view.lua

@@ -438,7 +438,7 @@ function M.abandon_all_windows()
   end
 end
 
----@param opts? nvim_tree.api.TreeIsVisibleOpts
+---@param opts table|nil
 ---@return boolean
 function M.is_visible(opts)
   if opts and opts.tabpage then
@@ -487,7 +487,7 @@ function M.focus(winnr, open_if_closed)
 end
 
 --- Retrieve the winid of the open tree.
----@param opts nvim_tree.api.TreeWinIdOpts|nil
+---@param opts ApiTreeWinIdOpts|nil
 ---@return number|nil winid unlike get_winnr(), this returns nil if the nvim-tree window is not visible
 function M.winid(opts)
   local tabpage = opts and opts.tabpage