docs(#3088): extract api/config/mappings.lua

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -1079,32 +1079,6 @@ marks.navigate.select()                *nvim-tree-api.marks.navigate.select()*
     Prompts for selection of a marked node, sorted by absolute paths.
     A folder will be focused, a file will be opened.
 
-==============================================================================
-API: Config                                             *nvim-tree-api.config*
-
-                           *nvim-tree-api.config.mappings.default_on_attach()*
-config.mappings.default_on_attach({bufnr})
-    Set all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config| {on_attach}
-
-    Parameters: ~
-      • {bufnr} (number) nvim-tree buffer number passed to |nvim_tree.Config| {on_attach}
-
-                                  *nvim-tree-api.config.mappings.get_keymap()*
-config.mappings.get_keymap()
-    Retrieves all buffer local mappings for nvim-tree.
-    These are the mappings that are applied by |nvim_tree.Config| {on_attach}, which
-    may include default mappings.
-
-    Return: ~
-        (table) as per |nvim_buf_get_keymap()|
-
-                          *nvim-tree-api.config.mappings.get_keymap_default()*
-config.mappings.get_keymap_default()
-    Retrieves the buffer local mappings for nvim-tree that are applied by
-    |nvim-tree-api.config.mappings.default_on_attach()|
-
-    Return: ~
-        (table) as per |nvim_buf_get_keymap()|
 
 ==============================================================================
 API: Commands                                         *nvim-tree-api.commands*
@@ -1266,7 +1240,7 @@ You are encouraged to copy these to your {on_attach} function. >lua
   -- END_DEFAULT_ON_ATTACH
 <
 Alternatively, you may apply these default mappings from your |nvim_tree.Config| {on_attach} via
-|nvim-tree-api.config.mappings.default_on_attach()| e.g. >lua
+|nvim_tree.api.config.mappings.default_on_attach()| e.g. >lua
 
   local function my_on_attach(bufnr)
     local api = require("nvim-tree.api")
@@ -2865,6 +2839,34 @@ Class: Config.Log                                       *nvim-tree-config-log*
 
 
 
+==============================================================================
+Lua module: nvim_tree.api.config                        *nvim-tree-api-config*
+
+                           *nvim_tree.api.config.mappings.default_on_attach()*
+default_on_attach({bufnr})
+    Apply all |nvim-tree-mappings-default|. Call from your |nvim_tree.Config|
+    {on_attach}.
+
+    Parameters: ~
+      • {bufnr}  (`integer`) use the `bufnr` passed to {on_attach}
+
+get_keymap()                      *nvim_tree.api.config.mappings.get_keymap()*
+    Retrieve all buffer local mappings for nvim-tree. These are the mappings
+    that are applied by |nvim_tree.Config| {on_attach}, which may include
+    default mappings.
+
+    Return: ~
+        (`vim.api.keyset.get_keymap[]`)
+
+                          *nvim_tree.api.config.mappings.get_keymap_default()*
+get_keymap_default()
+    Retrieves the buffer local mappings for nvim-tree that are applied by
+    |nvim_tree.api.config.mappings.default_on_attach()|
+
+    Return: ~
+        (`vim.api.keyset.get_keymap[]`)
+
+
 ==============================================================================
 Lua module: nvim_tree.api.tree                            *nvim-tree-api-tree*
 
@@ -2922,14 +2924,14 @@ find_file({opts})                             *nvim_tree.api.tree.find_file()*
 
     Parameters: ~
       • {opts}  (`table?`) optional
-                • {buf}? (`string|number`) Absolute/relative path OR |bufnr()|
+                • {buf}? (`string|integer`) 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}
+                • {winid}? (`integer`) Open the tree in the specified
+                  |window-ID|, 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.
@@ -2954,7 +2956,7 @@ is_tree_buf({bufnr})                        *nvim_tree.api.tree.is_tree_buf()*
     Checks if a buffer is an nvim-tree.
 
     Parameters: ~
-      • {bufnr}  (`number?`) 0 or nil for current buffer.
+      • {bufnr}  (`integer?`) 0 or nil for current buffer.
 
     Return: ~
         (`boolean`)
@@ -2979,8 +2981,8 @@ open({opts})                                       *nvim_tree.api.tree.open()*
                 • {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}
+                • {winid}? (`integer`) Open the tree in the specified
+                  |window-ID|, overrides {current_window}
                 • {find_file}? (`boolean`, default: false) Find the current
                   buffer.
                 • {update_root}? (`boolean`, default: false) Update root
@@ -3005,8 +3007,8 @@ resize({opts})                                   *nvim_tree.api.tree.resize()*
                 • {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.
+                • {absolute} (`integer`) Set the width.
+                • {relative} (`integer`) Increase or decrease the width.
 
 search_node()                               *nvim_tree.api.tree.search_node()*
     Open the search dialogue.
@@ -3019,8 +3021,8 @@ toggle({opts})                                   *nvim_tree.api.tree.toggle()*
                 • {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}
+                • {winid}? (`integer`) Open the tree in the specified
+                  |window-ID|, overrides {current_window}
                 • {find_file}? (`boolean`, default: false) Find the current
                   buffer.
                 • {focus}? (`boolean`, default: true) Focus the tree when
@@ -3055,14 +3057,14 @@ toggle_no_buffer_filter()
     Toggle |nvim_tree.Config.Filters| {no_buffer} filter.
 
 winid({opts})                                     *nvim_tree.api.tree.winid()*
-    Retrieve the winid of the open tree.
+    Retrieve the window of the open tree.
 
     Parameters: ~
       • {opts}  (`table?`) optional
                 • {tabpage}? (`integer`) |tab-ID| 0 or nil for current.
 
     Return: ~
-        (`integer?`) |winid|, nil if tree is not visible.
+        (`integer?`) |window-ID|, nil if tree is not visible.
 
 
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

lua/nvim-tree/api.lua

@@ -364,10 +364,15 @@ Api.marks.navigate.next = wrap_explorer_member("marks", "navigate_next")
 Api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
 Api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
+function Api.hydrate_config(tree)
+  Api.tree = tree
+
 Api.config.mappings.get_keymap = wrap(keymap.get_keymap)
 Api.config.mappings.get_keymap_default = wrap(keymap.get_keymap_default)
 Api.config.mappings.default_on_attach = keymap.default_on_attach
 
+end
+
 Api.diagnostics.hi_test = wrap(appearance_hi_test)
 
 Api.commands.get = wrap(function()

lua/nvim-tree/api/config/mappings.lua

@@ -0,0 +1,34 @@
+---@meta
+
+
+-- # TODO #3088 this should be api/config.lua however that results in a filename clash in gen_vimdoc_config.lua
+
+
+local nvim_tree = { api = { config = { mappings = {} } } }
+
+
+
+---Retrieve all buffer local mappings for nvim-tree. These are the mappings that are applied by [nvim_tree.Config] {on_attach}, which may include default mappings.
+---
+---@return vim.api.keyset.get_keymap[]
+function nvim_tree.api.config.mappings.get_keymap() end
+
+
+
+--- Retrieves the buffer local mappings for nvim-tree that are applied by [nvim_tree.api.config.mappings.default_on_attach()]
+---
+---@return vim.api.keyset.get_keymap[]
+function nvim_tree.api.config.mappings.get_keymap_default() end
+
+
+
+---Apply all [nvim-tree-mappings-default]. Call from your [nvim_tree.Config] {on_attach}.
+---
+---@param bufnr integer use the `bufnr` passed to {on_attach}
+function nvim_tree.api.config.mappings.default_on_attach(bufnr) end
+
+
+
+require("nvim-tree.api").hydrate_config(nvim_tree.api.config)
+
+return nvim_tree.api.tree

lua/nvim-tree/api/init.lua

@@ -1,3 +1,4 @@
 return {
-  tree = require("nvim-tree.api.tree")
+  config = require("nvim-tree.api.config.mappings"),
+  tree = require("nvim-tree.api.tree"),
 }

lua/nvim-tree/api/tree.lua

@@ -13,8 +13,8 @@ local nvim_tree = { api = { tree = {} } }
 ---(default: false)
 ---@field current_window? boolean
 ---
----Open the tree in the specified [winid], overrides {current_window}
----@field winid? number
+---Open the tree in the specified  [window-ID], overrides {current_window}
+---@field winid? integer
 ---
 ---Find the current buffer.
 ---(default: false)
@@ -41,8 +41,8 @@ function nvim_tree.api.tree.open(opts) end
 ---(default: false)
 ---@field current_window? boolean
 ---
----Open the tree in the specified [winid], overrides {current_window}
----@field winid? number
+---Open the tree in the specified [window-ID], overrides {current_window}
+---@field winid? integer
 ---
 ---Find the current buffer.
 ---(default: false)
@@ -93,10 +93,10 @@ function nvim_tree.api.tree.reload() end
 ---@field width nvim_tree.Config.View.WidthSpec|nvim_tree.Config.View.Width
 ---
 ---Set the width.
----@field absolute number
+---@field absolute integer
 ---
 ---Increase or decrease the width.
----@field relative number
+---@field relative integer
 
 ---Resize the tree, persisting the new size. Resets to [nvim_tree.Config.View] {width} when no {opts} provided.
 ---
@@ -143,8 +143,8 @@ function nvim_tree.api.tree.get_nodes() end
 ---@class nvim_tree.api.tree.find_file.Opts
 ---@inlinedoc
 ---
----Absolute/relative path OR [bufnr()] to find.
----@field buf? string|number
+---Absolute/relative path OR `bufnr` to find.
+---@field buf? string|integer
 ---
 ---Open the tree if necessary.
 ---(default: false)
@@ -154,8 +154,8 @@ function nvim_tree.api.tree.get_nodes() end
 ---(default: false)
 ---@field current_window? boolean
 ---
----Open the tree in the specified [winid], overrides {current_window}
----@field winid? number
+---Open the tree in the specified [window-ID], overrides {current_window}
+---@field winid? integer
 ---
 ---Update root after find, see [nvim_tree.Config.UpdateFocusedFile] {update_root}
 ---(default: false)
@@ -250,7 +250,8 @@ function nvim_tree.api.tree.toggle_help() end
 
 ---Checks if a buffer is an nvim-tree.
 ---
----@param bufnr? number 0 or nil for current buffer.
+---@param bufnr? integer 0 or nil for current buffer.
+---
 ---@return boolean
 function nvim_tree.api.tree.is_tree_buf(bufnr) end
 
@@ -280,10 +281,10 @@ function nvim_tree.api.tree.is_visible(opts) end
 ---[tab-ID] 0 or nil for current.
 ---@field tabpage? integer
 
----Retrieve the winid of the open tree.
+---Retrieve the window of the open tree.
 ---
 ---@param opts? nvim_tree.api.tree.winid.Opts optional
----@return integer? [winid], nil if tree is not visible.
+---@return integer? [window-ID], nil if tree is not visible.
 function nvim_tree.api.tree.winid(opts) end
 
 

scripts/gen_vimdoc_config.lua

@@ -31,6 +31,7 @@ local modules = {
   { helptag = "nvim-tree-config-experimental",        title = "Class: Config.Experimental",       path = "./lua/nvim_tree/_meta/config/experimental.lua", },
   { helptag = "nvim-tree-config-log",                 title = "Class: Config.Log",                path = "./lua/nvim_tree/_meta/config/log.lua", },
 
+  { helptag = "nvim-tree-api-config",                 title = "Lua module: nvim_tree.api.config", path = "./lua/nvim_tree/api/config/mappings.lua", },
   { helptag = "nvim-tree-api-tree",                   title = "Lua module: nvim_tree.api.tree",   path = "./lua/nvim_tree/api/tree.lua", },
 }
 
@@ -39,13 +40,13 @@ for _, m in ipairs(modules) do
   m.file = vim.fn.fnamemodify(m.path, ":t")
 end
 
---module name is derived by the generator as the file name with the first letter capitalised
+--section name is derived by the generator as the file name with the first letter capitalised
 --except for some like UI
 ---@type table<string, Module>
-local modules_by_name = {}
+local modules_by_section = {}
 for _, m in ipairs(modules) do
   local name = m.name or m.file:gsub(".lua", ""):gsub("^%l", string.upper)
-  modules_by_name[name] = m
+  modules_by_section[name] = m
 end
 
 ---@diagnostic disable-next-line: undefined-doc-name
@@ -62,17 +63,17 @@ local config = {
 
     section_fmt = function(name)
       print(string.format("section_fmt name=%s", name))
-      return modules_by_name[name] and modules_by_name[name].title or error(string.format("unknown module %s passed to section_fmt", name))
+      return modules_by_section[name] and modules_by_section[name].title or error(string.format("unknown module %s passed to section_fmt", name))
     end,
 
     helptag_fmt = function(name)
       print(string.format("helptag_fmt name=%s", name))
-      return modules_by_name[name] and modules_by_name[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name))
+      return modules_by_section[name] and modules_by_section[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name))
     end,
 
     -- optional, no default xform
     fn_xform = function(fun)
-      print(string.format("fn_xform fun=%s", vim.inspect(fun)))
+      -- print(string.format("fn_xform fun=%s", vim.inspect(fun)))
 
       if (fun.module) then
         -- generator doesn't strip meta

scripts/help-update.sh

@@ -49,4 +49,4 @@ sed -i -e "/${begin}/,/${end}/{ /${begin}/{p; r /tmp/DEFAULT_ON_ATTACH.help
            }; /${end}/p; d; }" doc/nvim-tree-lua.txt
 
 # TODO #3088 remove once all api references have been updated
-sed -i -e "s/nvim-tree-api.tree/nvim_tree.api.tree/g" doc/nvim-tree-lua.txt
+sed -i -e "s/nvim\-tree\-api\.tree\./nvim_tree.api.tree./g" doc/nvim-tree-lua.txt

scripts/lintdoc.sh

@@ -1,6 +1,5 @@
 #!/usr/bin/env sh
 
-
 # Wrapper around Nvim help linter lintdoc.lua, run as part of Nvim's make lintdoc target.
 #
 # Requires Nvim to have been built.