doc(#2934): add nvim_tree.api classes to help

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -1,9 +1,9 @@
-*nvim-tree.lua* A File Explorer For Neovim Written In Lua
+*nvim-tree* A File Explorer For Neovim Written In Lua
 
 Author: Yazdani Kiyan
 
 ==============================================================================
-CONTENTS                                                           *nvim-tree*
+CONTENTS
 
   1. Introduction                             |nvim-tree-introduction|
   2. Quickstart                               |nvim-tree-quickstart|
@@ -3445,7 +3445,7 @@ highlight group is not, hard linking as follows: >
 |nvim-tree-api.tree.winid()|
 
 ==============================================================================
-Lua module: nvim_tree.Config                                *nvim-tree-config*
+Lua module: nvim_tree                                       *nvim-tree-module*
 
 *nvim_tree.Config*
 
@@ -4262,6 +4262,96 @@ Lua module: nvim_tree.Config                                *nvim-tree-config*
 
 
 
+==============================================================================
+Lua module: nvim_tree.api                                      *nvim-tree-api*
+
+*nvim_tree.api.CollapseOpts*
+
+    Fields: ~
+      • {keep_buffers}?  (`boolean`) do not collapse nodes with open buffers
+
+*nvim_tree.api.NodeBufferOpts*
+
+    Fields: ~
+      • {force}?  (`boolean`) delete/wipe even if buffer is modified, default
+                  false
+
+*nvim_tree.api.NodeEditOpts*
+
+    Fields: ~
+      • {quit_on_open}?  (`boolean`) quits the tree when opening the file
+      • {focus}?         (`boolean`) keep focus in the tree when opening the
+                         file
+
+*nvim_tree.api.TreeExpandOpts*
+
+    Fields: ~
+      • {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.
+
+*nvim_tree.api.TreeFindFileOpts*
+
+    Fields: ~
+      • {buf}?             (`string|number`) absolute/relative path OR bufnr
+                           to find
+      • {open}?            (`boolean`) open the tree if necessary
+      • {current_window}?  (`boolean`) requires open, open in the current
+                           window
+      • {winid}?           (`number`) open the tree in the specified |winid|,
+                           overrides current_window
+      • {update_root}?     (`boolean`) see
+                           |nvim-tree.update_focused_file.update_root|
+      • {focus}?           (`boolean`) focus the tree
+
+*nvim_tree.api.TreeIsVisibleOpts*
+
+    Fields: ~
+      • {tabpage}?      (`number`) as per |nvim_get_current_tabpage()|
+      • {any_tabpage}?  (`boolean`) visible on any tab, default false
+
+*nvim_tree.api.TreeOpenOpts*
+
+    Fields: ~
+      • {path}?            (`string`) root directory for the tree
+      • {current_window}?  (`boolean`) open the tree in the current window
+      • {winid}?           (`number`) open the tree in the specified winid,
+                           overrides current_window
+      • {find_file}?       (`boolean`) find the current buffer
+      • {update_root}?     (`boolean`) requires find_file, see
+                           |nvim-tree.update_focused_file.update_root|
+      • {focus}?           (`boolean`) focus the tree when opening, default
+                           true
+
+*nvim_tree.api.TreeResizeOpts*
+
+    Fields: ~
+      • {width}?     (`string|function|number|table`) new
+                     |nvim-tree.view.width| value
+      • {absolute}?  (`number`) set the width
+      • {relative}?  (`number`) relative width adjustment
+
+*nvim_tree.api.TreeToggleOpts*
+
+    Fields: ~
+      • {path}?            (`string`) root directory for the tree
+      • {current_window}?  (`boolean`) open the tree in the current window
+      • {winid}?           (`number`) open the tree in the specified |winid|,
+                           overrides current_window
+      • {find_file}?       (`boolean`) find the current buffer
+      • {update_root}?     (`boolean`) requires find_file, see
+                           |nvim-tree.update_focused_file.update_root|
+      • {focus}?           (`boolean`) focus the tree when opening, default
+                           true
+
+*nvim_tree.api.TreeWinIdOpts*
+
+    Fields: ~
+      • {tabpage}?  (`number`) tabpage, 0 or nil for current, default nil
+
+
+
 ==============================================================================
 Lua module: nvim_tree.api.decorator                  *nvim-tree-api-decorator*
 

scripts/gen_vimdoc_config.lua

@@ -1,36 +1,61 @@
 ---@diagnostic disable: undefined-doc-name
 
+-- module name is derived as the file name with the first letter capitalised
+local modules = {
+  Api = {
+    order = 2,
+    helptag = "nvim-tree-api",
+    title = "Lua module: nvim_tree.api",
+    path = "lua/nvim-tree/_meta/api.lua",
+  },
+  Config = {
+    order = 1,
+    helptag = "nvim-tree-module",
+    title = "Lua module: nvim_tree",
+    path = "lua/nvim-tree/_meta/config.lua",
+  },
+  Api_decorator = {
+    order = 3,
+    helptag = "nvim-tree-api-decorator",
+    title = "Lua module: nvim_tree.api.decorator",
+    path = "lua/nvim-tree/_meta/api_decorator.lua",
+  },
+}
+
 --- @type table<string,nvim.gen_vimdoc.Config>
 local config = {
   decorator = {
     filename = "nvim-tree-lua.txt",
-    -- filename = "decorator.txt",
-    section_order = {
-      "config.lua",
-      "api_decorator.lua",
-    },
-    files = {
-      -- module is derived soley from the file name, first letter capitalised
-      "lua/nvim-tree/_meta/api_decorator.lua",
-      "lua/nvim-tree/_meta/config.lua",
-    },
-    section_fmt = function(name)
-      if name == "Config" then
-        return "Lua module: nvim_tree.Config"
-      elseif name == "Api_decorator" then
-        return "Lua module: nvim_tree.api.decorator"
+
+    -- file name sets order
+    section_order = (function()
+      local ret = {}
+      for _, c in pairs(modules) do
+        ret[c.order] = vim.fn.fnamemodify(c.path, ":t")
+      end
+      return ret
+    end)(),
+
+    -- full path, will be ordered by section_order
+    files = (function()
+      local ret = {}
+      for _, c in pairs(modules) do
+        table.insert(ret, c.path)
       end
-      error(string.format("unknown module %s passed to section_fmt", name))
+      return ret
+    end)(),
+
+    -- section title
+    section_fmt = function(name)
+      return modules[name] and modules[name].title or error(string.format("unknown module %s passed to section", name))
     end,
+
+    -- section's help tag
     helptag_fmt = function(name)
-      -- used to locate the first section only, others will be rendered after
-      if name == "Config" then
-        return "nvim-tree-config"
-      elseif name == "Api_decorator" then
-        return "nvim-tree-api-decorator"
-      end
-      error(string.format("unknown module %s passed to helptag_fmt", name))
+      return modules[name] and modules[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name))
     end,
+
+    -- class/function's help tag
     fn_helptag_fmt = function(fun)
       -- Modified copy of fn_helptag_fmt_common
       -- Uses fully qualified class name in the tag for methods.