doc: clarify open/toggle defaults, more robust legacy argument handling

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -1251,24 +1251,24 @@ api.tree.open({opts})                              *nvim-tree.api.tree.open()*
     Open the tree, focusing it if already open.
 
     Parameters: ~
-      • {opts} (table) optional parameters
+      • {opts} (table) optional parameters with boolean defaults
 
     Options: ~
-      • {path}           (string)  root directory for the tree
-      • {current_window} (boolean) open the tree in the current window
+      • {path}           (string)         root directory for the tree
+      • {current_window} (boolean, false) open the tree in the current window
 
 api.tree.toggle({opts})                          *nvim-tree.api.tree.toggle()*
     Open or close the tree.
 
     Parameters: ~
-      • {opts} (table) optional parameters
+      • {opts} (table) optional parameters with boolean defaults
 
     Options: ~
-      • {path}           (string)  root directory for the tree
-      • {current_window} (boolean) open the tree in the current window
-      • {focus}          (boolean) focus the tree when opening
-      • {find_file}      (boolean) find the current buffer
-      • {update_root}    (boolean) see |nvim-tree.update_focused_file.update_root|
+      • {path}           (string)         root directory for the tree
+      • {current_window} (boolean, false) open the tree in the current window
+      • {focus}          (boolean, true)  focus the tree when opening
+      • {find_file}      (boolean, false) find the current buffer
+      • {update_root}    (boolean, false) see |nvim-tree.update_focused_file.update_root|
 
 api.tree.close()                                   *nvim-tree.api.tree.close()*
     Close the tree, affecting all tabs as per |nvim-tree.tab.sync.close|

lua/nvim-tree.lua

@@ -75,7 +75,7 @@ M.on_keypress = require("nvim-tree.actions.dispatch").dispatch
 ---@param opts ApiTreeOpenOpts|nil|string
 function M.open(opts)
   -- legacy arguments
-  if type(opts) ~= "table" then
+  if type(opts) == "string" then
     opts = {
       path = opts,
     }
@@ -184,17 +184,28 @@ end
 ---@param opts ApiTreeToggleOpts|nil|boolean
 function M.toggle(opts, no_focus, cwd, bang)
   -- legacy arguments
-  if type(opts) ~= "table" then
+  if type(opts) == "boolean" then
     opts = {
-      path = cwd,
-      focus = not no_focus,
-      find_file = opts,
-      update_root = bang,
+      find_file = opts
     }
+    if type(cwd) == "string" then
+      opts.path = cwd
+    end
+    if type(no_focus) == "boolean" then
+      opts.focus = not no_focus
+    end
+    if type(bang) == "boolean" then
+      opts.update_root = bang
+    end
   end
 
   opts = opts or {}
 
+  -- defaults
+  if opts.focus == nil then
+    opts.focus = true
+  end
+
   -- sanitise path
   if type(opts.path) ~= "string" or vim.fn.isdirectory(opts.path) == 0 then
     opts.path = nil

lua/nvim-tree/api.lua

@@ -18,16 +18,16 @@ end
 
 ---@class ApiTreeOpenOpts
 ---@field path string|nil path
----@field current_window boolean|nil
+---@field current_window boolean|nil default false
 
 Api.tree.open = require("nvim-tree").open
 
 ---@class ApiTreeToggleOpts
 ---@field path string|nil
----@field current_window boolean|nil
----@field focus boolean|nil
----@field find_file boolean|nil
----@field update_root boolean|nil
+---@field current_window boolean|nil default false
+---@field focus boolean|nil default true
+---@field find_file boolean|nil default false
+---@field update_root boolean|nil default false
 
 Api.tree.toggle = require("nvim-tree").toggle