docs(#3088): extract fs.copy, fix api node param optionality, move legacy api to legacy.lua

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -2457,36 +2457,6 @@ API: fs                                                     *nvim-tree-api-fs*
 clear_clipboard()                         *nvim_tree.api.fs.clear_clipboard()*
     Clear the nvim-tree clipboard.
 
-copy.absolute_path({node})             *nvim_tree.api.fs.copy.absolute_path()*
-    Copy the absolute path to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
-
-copy.basename({node})                       *nvim_tree.api.fs.copy.basename()*
-    Copy the name with extension omitted to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
-
-copy.filename({node})                       *nvim_tree.api.fs.copy.filename()*
-    Copy the name to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
-
-copy.node({node})                               *nvim_tree.api.fs.copy.node()*
-    Copy to the nvim-tree clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
-
-copy.relative_path({node})             *nvim_tree.api.fs.copy.relative_path()*
-    Copy the path relative to the tree root to the system clipboard.
-
-    Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
-
 create({node})                                     *nvim_tree.api.fs.create()*
     Prompt to create a file or directory.
 
@@ -2497,21 +2467,21 @@ create({node})                                     *nvim_tree.api.fs.create()*
     Multiple directories/files may be created e.g. `"foo/bar/baz"`
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 cut({node})                                           *nvim_tree.api.fs.cut()*
     Cut to the nvim-tree clipboard.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 paste({node})                                       *nvim_tree.api.fs.paste()*
     Paste from the nvim-tree clipboard.
 
     If {node} is a file it will pasted in the parent directory.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 print_clipboard()                         *nvim_tree.api.fs.print_clipboard()*
     Print the contents of the nvim-tree clipboard.
@@ -2520,43 +2490,77 @@ remove({node})                                     *nvim_tree.api.fs.remove()*
     Delete from the file system.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 rename({node})                                     *nvim_tree.api.fs.rename()*
     Prompt to rename by name.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 rename_basename({node})                   *nvim_tree.api.fs.rename_basename()*
     Prompt to rename by name with extension omitted.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 rename_full({node})                           *nvim_tree.api.fs.rename_full()*
     Prompt to rename by absolute path.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 rename_node({node})                           *nvim_tree.api.fs.rename_node()*
     Prompt to rename.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 rename_sub({node})                             *nvim_tree.api.fs.rename_sub()*
     Prompt to rename by absolute path with name omitted.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
 
 trash({node})                                       *nvim_tree.api.fs.trash()*
     Trash as per |nvim_tree.config.trash|
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`)
+      • {node}  (`nvim_tree.api.Node?`)
+
+
+==============================================================================
+API: fs.copy                                           *nvim-tree-api-fs-copy*
+
+absolute_path({node})                  *nvim_tree.api.fs.copy.absolute_path()*
+    Copy the absolute path to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+basename({node})                            *nvim_tree.api.fs.copy.basename()*
+    Copy the name with extension omitted to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+filename({node})                            *nvim_tree.api.fs.copy.filename()*
+    Copy the name to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+node({node})                                    *nvim_tree.api.fs.copy.node()*
+    Copy to the nvim-tree clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
+
+relative_path({node})                  *nvim_tree.api.fs.copy.relative_path()*
+    Copy the path relative to the tree root to the system clipboard.
+
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`)
 
 
 ==============================================================================
@@ -2636,7 +2640,7 @@ toggle({node})                                  *nvim_tree.api.marks.toggle()*
     Toggle mark.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`) file or directory
+      • {node}  (`nvim_tree.api.Node?`) file or directory
 
 
 ==============================================================================
@@ -2647,7 +2651,7 @@ buffer.delete({node}, {opts})             *nvim_tree.api.node.buffer.delete()*
     |:bdelete|!
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`) file
+      • {node}  (`nvim_tree.api.Node?`) file
       • {opts}  (`table?`)
                 • {force}? (`boolean`, default: false) Proceed even if the
                   buffer is modified.
@@ -2976,14 +2980,14 @@ change_root_to_node({node})         *nvim_tree.api.tree.change_root_to_node()*
     Change the tree's root to a folder node or the parent of a file node.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
                                   *nvim_tree.api.tree.change_root_to_parent()*
 change_root_to_parent({node})
     Change the tree's root to the parent of a node.
 
     Parameters: ~
-      • {node}  (`nvim_tree.api.Node`) directory or file
+      • {node}  (`nvim_tree.api.Node?`) directory or file
 
 close()                                           *nvim_tree.api.tree.close()*
     Close the tree, affecting all tabs as per |nvim_tree.config.tab.sync|

lua/nvim-tree/_meta/api/fs.lua

@@ -1,43 +1,13 @@
 ---@meta
 local nvim_tree = { api = { fs = {} } }
 
+nvim_tree.api.fs.copy = require("nvim-tree._meta.api.fs.copy");
+
 ---
 ---Clear the nvim-tree clipboard.
 ---
 function nvim_tree.api.fs.clear_clipboard() end
 
-nvim_tree.api.fs.copy = {}
-
----
----Copy the absolute path to the system clipboard.
----
----@param node nvim_tree.api.Node
-function nvim_tree.api.fs.copy.absolute_path(node) end
-
----
----Copy the name with extension omitted to the system clipboard.
----
----@param node nvim_tree.api.Node
-function nvim_tree.api.fs.copy.basename(node) end
-
----
----Copy the name to the system clipboard.
----
----@param node nvim_tree.api.Node
-function nvim_tree.api.fs.copy.filename(node) end
-
----
----Copy to the nvim-tree clipboard.
----
----@param node nvim_tree.api.Node
-function nvim_tree.api.fs.copy.node(node) end
-
----
----Copy the path relative to the tree root to the system clipboard.
----
----@param node nvim_tree.api.Node
-function nvim_tree.api.fs.copy.relative_path(node) end
-
 ---
 ---Prompt to create a file or directory.
 ---
@@ -47,21 +17,21 @@ function nvim_tree.api.fs.copy.relative_path(node) end
 ---
 ---Multiple directories/files may be created e.g. `"foo/bar/baz"`
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.create(node) end
 
 ---
 ---Cut to the nvim-tree clipboard.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.cut(node) end
 
 ---
 ---Paste from the nvim-tree clipboard.
 ---
 ---If {node} is a file it will pasted in the parent directory.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.paste(node) end
 
 ---
@@ -72,43 +42,43 @@ function nvim_tree.api.fs.print_clipboard() end
 ---
 ---Delete from the file system.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.remove(node) end
 
 ---
 ---Prompt to rename by name.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.rename(node) end
 
 ---
 ---Prompt to rename by name with extension omitted.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.rename_basename(node) end
 
 ---
 ---Prompt to rename by absolute path.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.rename_full(node) end
 
 ---
 ---Prompt to rename.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.rename_node(node) end
 
 ---
 ---Prompt to rename by absolute path with name omitted.
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.rename_sub(node) end
 
 ---
 ---Trash as per |nvim_tree.config.trash|
 ---
----@param node nvim_tree.api.Node
+---@param node? nvim_tree.api.Node
 function nvim_tree.api.fs.trash(node) end
 
 return nvim_tree.api.fs

lua/nvim-tree/_meta/api/fs/copy.lua

@@ -0,0 +1,34 @@
+---@meta
+local nvim_tree = { api = { fs = { copy = {} } } }
+
+---
+---Copy the absolute path to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.absolute_path(node) end
+
+---
+---Copy the name with extension omitted to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.basename(node) end
+
+---
+---Copy the name to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.filename(node) end
+
+---
+---Copy to the nvim-tree clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.node(node) end
+
+---
+---Copy the path relative to the tree root to the system clipboard.
+---
+---@param node? nvim_tree.api.Node
+function nvim_tree.api.fs.copy.relative_path(node) end
+
+return nvim_tree.api.fs.copy

lua/nvim-tree/_meta/api/marks.lua

@@ -16,7 +16,7 @@ function nvim_tree.api.marks.list() end
 ---
 ---Toggle mark.
 ---
----@param node nvim_tree.api.Node file or directory
+---@param node? nvim_tree.api.Node file or directory
 function nvim_tree.api.marks.toggle(node) end
 
 ---

lua/nvim-tree/_meta/api/node.lua

@@ -18,7 +18,7 @@ nvim_tree.api.node.buffer = {}
 ---
 ---Deletes node's related buffer, if one exists. Executes [:bdelete] or [:bdelete]!
 ---
----@param node nvim_tree.api.Node file
+---@param node? nvim_tree.api.Node file
 ---@param opts? nvim_tree.api.node.buffer.RemoveOpts
 function nvim_tree.api.node.buffer.delete(node, opts) end
 

lua/nvim-tree/_meta/api/tree.lua

@@ -115,13 +115,13 @@ function nvim_tree.api.tree.change_root(path) end
 ---
 ---Change the tree's root to a folder node or the parent of a file node.
 ---
----@param node nvim_tree.api.Node directory or file
+---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.tree.change_root_to_node(node) end
 
 ---
 ---Change the tree's root to the parent of a node.
 ---
----@param node nvim_tree.api.Node directory or file
+---@param node? nvim_tree.api.Node directory or file
 function nvim_tree.api.tree.change_root_to_parent(node) end
 
 ---