docs(#3088): extract api/tree.lua

Author: alex-courtis

.luacheckrc

@@ -5,6 +5,7 @@ M.self = false
 
 M.ignore = {
   "631",  -- max_line_length
+  "212", -- TODO #3088 make luacheck understand @meta
 }
 
 -- Global objects defined by the C code

doc/nvim-tree-lua.txt

@@ -3071,82 +3071,201 @@ Class: Config.Log                                       *nvim-tree-config-log*
 ==============================================================================
 Lua module: nvim_tree.api.tree                            *nvim-tree-api-tree*
 
-focus()                                           *nvim_tree.api.tree.focus()*
-    TODO #3088 descriptions are needed to properly format the functions
+change_root({path})                         *nvim_tree.api.tree.change_root()*
+    Change the tree's root to a path.
+
+    Parameters: ~
+      • {path}  (`string?`) absolute or relative path.
 
-nvim_tree.api.tree.change_root()            *nvim_tree.api.tree.change_root()*
+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.
 
-                                    *nvim_tree.api.tree.change_root_to_node()*
-nvim_tree.api.tree.change_root_to_node()
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`) directory or file
 
                                   *nvim_tree.api.tree.change_root_to_parent()*
-nvim_tree.api.tree.change_root_to_parent()
+change_root_to_parent({node})
+    Change the tree's root to the parent of a node.
 
-nvim_tree.api.tree.close()                        *nvim_tree.api.tree.close()*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node`) directory or file
 
-                                      *nvim_tree.api.tree.close_in_all_tabs()*
-nvim_tree.api.tree.close_in_all_tabs()
+close()                                           *nvim_tree.api.tree.close()*
+    Close the tree, affecting all tabs as per |nvim_tree.Config.Tab.Sync|
+    {close}
 
-                                      *nvim_tree.api.tree.close_in_this_tab()*
-nvim_tree.api.tree.close_in_this_tab()
+close_in_all_tabs()                   *nvim_tree.api.tree.close_in_all_tabs()*
+    Close the tree in all tabs.
 
-nvim_tree.api.tree.collapse_all()          *nvim_tree.api.tree.collapse_all()*
+close_in_this_tab()                   *nvim_tree.api.tree.close_in_this_tab()*
+    Close the tree in this tab only.
 
-nvim_tree.api.tree.expand_all()              *nvim_tree.api.tree.expand_all()*
+collapse_all({opts})                       *nvim_tree.api.tree.collapse_all()*
+    Collapse the tree.
 
-nvim_tree.api.tree.find_file()                *nvim_tree.api.tree.find_file()*
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {keep_buffers}? (`boolean`, default: false) Do not collapse
+                  nodes with open buffers.
 
-                                  *nvim_tree.api.tree.get_node_under_cursor()*
-nvim_tree.api.tree.get_node_under_cursor()
+expand_all({node}, {opts})                   *nvim_tree.api.tree.expand_all()*
+    Recursively expand all nodes under the tree root or specified folder.
 
-nvim_tree.api.tree.get_nodes()                *nvim_tree.api.tree.get_nodes()*
+    Parameters: ~
+      • {node}  (`nvim_tree.api.Node?`) directory
+      • {opts}  (`table?`) optional
+                • {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.
+
+find_file({opts})                             *nvim_tree.api.tree.find_file()*
+    Find and focus a file or folder in the tree. Finds current buffer unless
+    otherwise specified.
 
-nvim_tree.api.tree.is_tree_buf()            *nvim_tree.api.tree.is_tree_buf()*
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {buf}? (`string|number`) Absolute/relative path OR |bufnr()|
+                  to find.
+                • {open}? (`boolean`, default: false) Open the tree if
+                  necessary.
+                • {current_window}? (`boolean`, default: false) Requires
+                  {open}: open in the current window.
+                • {winid}? (`number`) Open the tree in the specified |winid|,
+                  overrides {current_window}
+                • {update_root}? (`boolean`, default: false) Update root after
+                  find, see |nvim_tree.Config.UpdateFocusedFile| {update_root}
+                • {focus}? (`boolean`, default: false) Focus the tree window.
+
+focus()                                           *nvim_tree.api.tree.focus()*
+    Focus the tree, opening it if necessary. Retained for compatibility, use
+    |nvim_tree.api.tree.open()| with no arguments instead.
 
-nvim_tree.api.tree.is_visible()              *nvim_tree.api.tree.is_visible()*
+get_node_under_cursor()           *nvim_tree.api.tree.get_node_under_cursor()*
+    Retrieve the currently focused node.
 
-nvim_tree.api.tree.reload()                      *nvim_tree.api.tree.reload()*
+    Return: ~
+        (`nvim_tree.api.Node?`) nil if tree is not visible.
 
-nvim_tree.api.tree.resize()                      *nvim_tree.api.tree.resize()*
+get_nodes()                                   *nvim_tree.api.tree.get_nodes()*
+    Retrieve a hierarchical list of all the nodes.
 
-nvim_tree.api.tree.search_node()            *nvim_tree.api.tree.search_node()*
+    Return: ~
+        (`nvim_tree.api.Node[]`)
 
-nvim_tree.api.tree.toggle()                      *nvim_tree.api.tree.toggle()*
+is_tree_buf({bufnr})                        *nvim_tree.api.tree.is_tree_buf()*
+    Checks if a buffer is an nvim-tree.
 
-                                   *nvim_tree.api.tree.toggle_custom_filter()*
-nvim_tree.api.tree.toggle_custom_filter()
+    Parameters: ~
+      • {bufnr}  (`number?`) 0 or nil for current buffer.
 
-                                  *nvim_tree.api.tree.toggle_enable_filters()*
-nvim_tree.api.tree.toggle_enable_filters()
+    Return: ~
+        (`boolean`)
+
+is_visible({opts})                           *nvim_tree.api.tree.is_visible()*
+    Checks if nvim-tree is visible on the current, specified or any tab.
+
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {tabpage}? (`integer`) |tab-ID| 0 or nil for current.
+                • {any_tabpage}? (`boolean`, default: false) Visible on any
+                  tab.
+
+    Return: ~
+        (`boolean`)
+
+open({opts})                                       *nvim_tree.api.tree.open()*
+    Open the tree, focusing it if already open.
+
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {path}? (`string`) Root directory for the tree
+                • {current_window}? (`boolean`, default: false) Open the tree
+                  in the current window
+                • {winid}? (`number`) Open the tree in the specified |winid|,
+                  overrides {current_window}
+                • {find_file}? (`boolean`, default: false) Find the current
+                  buffer.
+                • {update_root}? (`boolean`, default: false) Update root
+                  following {find_file}, see
+                  |nvim_tree.Config.UpdateFocusedFile| {update_root}
+
+reload()                                         *nvim_tree.api.tree.reload()*
+    Refresh the tree. Does nothing if closed.
+
+resize({opts})                                   *nvim_tree.api.tree.resize()*
+    Resize the tree, persisting the new size. Resets to
+    |nvim_tree.Config.View| {width} when no {opts} provided.
+
+    Only one option is supported, priority order: {width}, {absolute},
+    {relative}.
+
+    {absolute} and {relative} do nothing when |nvim_tree.Config.View| {width}
+    is a function.
+
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {width}
+                  (`nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width`)
+                  New |nvim_tree.Config.View| {width} value.
+                • {absolute} (`number`) Set the width.
+                • {relative} (`number`) Increase or decrease the width.
+
+search_node()                               *nvim_tree.api.tree.search_node()*
+    Open the search dialogue.
+
+toggle({opts})                                   *nvim_tree.api.tree.toggle()*
+    Open or close the tree.
+
+    Parameters: ~
+      • {opts}  (`table?`) optional
+                • {path}? (`string`) Root directory for the tree
+                • {current_window}? (`boolean`, default: false) Open the tree
+                  in the current window
+                • {winid}? (`number`) Open the tree in the specified |winid|,
+                  overrides {current_window}
+                • {find_file}? (`boolean`, default: false) Find the current
+                  buffer.
+                • {focus}? (`boolean`, default: true) Focus the tree when
+                  opening.
+
+toggle_custom_filter()             *nvim_tree.api.tree.toggle_custom_filter()*
+    Toggle |nvim_tree.Config.Filters| {custom} filter.
+
+toggle_enable_filters()           *nvim_tree.api.tree.toggle_enable_filters()*
+    Toggle |nvim_tree.Config.Filters| {enable} all filters.
 
                                 *nvim_tree.api.tree.toggle_git_clean_filter()*
-nvim_tree.api.tree.toggle_git_clean_filter()
+toggle_git_clean_filter()
+    Toggle |nvim_tree.Config.Filters| {git_clean} filter.
 
                                 *nvim_tree.api.tree.toggle_gitignore_filter()*
-nvim_tree.api.tree.toggle_gitignore_filter()
+toggle_gitignore_filter()
+    Toggle |nvim_tree.Config.Filters| {git_ignored} filter.
 
-nvim_tree.api.tree.toggle_help()            *nvim_tree.api.tree.toggle_help()*
+toggle_help()                               *nvim_tree.api.tree.toggle_help()*
+    Toggle help view.
 
-                                   *nvim_tree.api.tree.toggle_hidden_filter()*
-nvim_tree.api.tree.toggle_hidden_filter()
+toggle_hidden_filter()             *nvim_tree.api.tree.toggle_hidden_filter()*
+    Toggle |nvim_tree.Config.Filters| {dotfiles} filter.
 
                               *nvim_tree.api.tree.toggle_no_bookmark_filter()*
-nvim_tree.api.tree.toggle_no_bookmark_filter()
+toggle_no_bookmark_filter()
+    Toggle |nvim_tree.Config.Filters| {no_bookmark} filter.
 
                                 *nvim_tree.api.tree.toggle_no_buffer_filter()*
-nvim_tree.api.tree.toggle_no_buffer_filter()
-
-nvim_tree.api.tree.winid()                        *nvim_tree.api.tree.winid()*
+toggle_no_buffer_filter()
+    Toggle |nvim_tree.Config.Filters| {no_buffer} filter.
 
-open({opts})                                       *nvim_tree.api.tree.open()*
+winid({opts})                                     *nvim_tree.api.tree.winid()*
+    Retrieve the winid of the open tree.
 
     Parameters: ~
-      • {opts}  (`table?`) A table with the following fields:
-                • {path} (`string?`) path
-                • {current_window} (`boolean?`) default false
-                • {winid} (`number?`)
-                • {find_file} (`boolean?`) default false
-                • {update_root} (`boolean?`) default false
+      • {opts}  (`table?`) optional
+                • {tabpage}? (`integer`) |tab-ID| 0 or nil for current.
+
+    Return: ~
+        (`integer?`) |winid|, nil if tree is not visible.
 
 
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: