docs(#3088): move legacy api into api.impl.legacy, fixes following testing

Author: alex-courtis

lua/nvim-tree/api.lua

@@ -82,7 +82,7 @@ local api = {
   events = require("nvim-tree._meta.api.events"),
   filter = require("nvim-tree._meta.api.filter"),
   fs = require("nvim-tree._meta.api.fs"),
-  git = require("nvim-tree._meta.api._git"),
+  git = require("nvim-tree._meta.api.git"),
   health = require("nvim-tree._meta.api.health"),
   map = require("nvim-tree._meta.api.map"),
   marks = require("nvim-tree._meta.api.marks"),

lua/nvim-tree/api/impl/legacy.lua

@@ -0,0 +1,25 @@
+---Silently create new api entries pointing legacy functions to current
+---@param api table not properly typed to prevent LSP from referencing implementations
+return function(api)
+  api.config = api.config or {}
+  api.config.mappings = api.config.mappings or {}
+  api.config.mappings.get_keymap = api.map.keymap.current
+  api.config.mappings.get_keymap_default = api.map.keymap.default
+  api.config.mappings.default_on_attach = api.map.on_attach.default
+
+  api.live_filter = api.live_filter or {}
+  api.live_filter.start = api.filter.live.start
+  api.live_filter.clear = api.filter.live.clear
+
+  api.tree = api.tree or {}
+  api.tree.toggle_enable_filters = api.filter.toggle
+  api.tree.toggle_gitignore_filter = api.filter.git.ignored.toggle
+  api.tree.toggle_git_clean_filter = api.filter.git.clean.toggle
+  api.tree.toggle_no_buffer_filter = api.filter.no_buffer.toggle
+  api.tree.toggle_custom_filter = api.filter.custom.toggle
+  api.tree.toggle_hidden_filter = api.filter.dotfiles.toggle
+  api.tree.toggle_no_bookmark_filter = api.filter.no_bookmark.toggle
+
+  api.diagnostics = api.diagnostics or {}
+  api.diagnostics.hi_test = api.health.hi_test
+end

lua/nvim-tree/api/impl/post.lua

@@ -6,8 +6,11 @@
 ---This is expensive as there are many cascading requires and is avoided
 ---until after setup has been called, so that the user may require API cheaply.
 
-local view = require("nvim-tree.view")
 local actions = require("nvim-tree.actions")
+local help = require("nvim-tree.help")
+local keymap = require("nvim-tree.keymap")
+local utils = require("nvim-tree.utils")
+local view = require("nvim-tree.view")
 
 local DirectoryNode = require("nvim-tree.node.directory")
 local FileLinkNode = require("nvim-tree.node.file-link")
@@ -131,7 +134,7 @@ local function open_or_expand_or_dir_up(mode, toggle_group)
 end
 
 ---Hydrate all implementations barring those that were called during hydrate_pre
----@param api table
+---@param api table not properly typed to prevent LSP from referencing implementations
 local function hydrate_post(api)
   api.tree.open = actions.tree.open.fn
   api.tree.focus = api.tree.open
@@ -157,8 +160,8 @@ local function hydrate_post(api)
   api.tree.collapse_all = actions.tree.collapse.all
 
   api.tree.expand_all = wrap_node(wrap_explorer("expand_all"))
-  api.tree.toggle_help = function() require("nvim-tree.help").toggle() end
-  api.tree.is_tree_buf = function() require("nvim-tree.utils").is_nvim_tree_buf() end
+  api.tree.toggle_help = help.toggle
+  api.tree.is_tree_buf = utils.is_nvim_tree_buf
 
   api.tree.is_visible = view.is_visible
 
@@ -248,15 +251,15 @@ local function hydrate_post(api)
   api.marks.navigate.prev = wrap_explorer_member("marks", "navigate_prev")
   api.marks.navigate.select = wrap_explorer_member("marks", "navigate_select")
 
-  api.map.get_keymap = function() require("nvim-tree.keymap").get_keymap() end
+  api.map.keymap.current = keymap.get_keymap
 end
 
 ---Re-hydrate api
----@param api table
+---@param api table not properly typed to prevent LSP from referencing implementations
 return function(api)
   -- All concrete implementations
   hydrate_post(api)
 
   -- (Re)hydrate any legacy by mapping to function set above
-  require("nvim-tree.legacy").api_map(api)
+  require("nvim-tree.api.impl.legacy")(api)
 end

lua/nvim-tree/api/impl/pre.lua

@@ -30,6 +30,7 @@ local function hydrate_error(t)
 end
 
 ---Hydrate implementations that may be called pre setup
+---@param api table not properly typed to prevent LSP from referencing implementations
 local function hydrate_pre(api)
   --
   -- Essential
@@ -51,7 +52,7 @@ local function hydrate_pre(api)
   --
   api.commands.get = commands.get
 
-  api.map.get_keymap_default = keymap.get_keymap_default
+  api.map.keymap.default = keymap.get_keymap_default
 
 
   --
@@ -65,6 +66,7 @@ local function hydrate_pre(api)
 end
 
 ---Hydrate api
+---@param api table not properly typed to prevent LSP from referencing implementations
 return function(api)
   -- Default: error
   hydrate_error(api)
@@ -73,5 +75,5 @@ return function(api)
   hydrate_pre(api)
 
   -- Hydrate any legacy by mapping to function set above
-  require("nvim-tree.legacy").api_map(api)
+  require("nvim-tree.api.impl.legacy")(api)
 end

lua/nvim-tree/legacy.lua

@@ -2,10 +2,6 @@ local notify = require("nvim-tree.notify")
 
 local M = {}
 
---
---Functions
---
-
 --- Create empty sub-tables if not present
 ---@param tbl table to create empty inside of
 ---@param path string dot separated string of sub-tables
@@ -54,10 +50,6 @@ local function move(src, src_path, src_pos, dst, dst_path, dst_pos, remove)
   end
 end
 
---
---Config
---
-
 -- silently move, please add to help nvim-tree-legacy-opts
 local function refactored(opts)
   -- 2022/06/20
@@ -159,33 +151,4 @@ function M.migrate_legacy_options(opts)
   removed(opts)
 end
 
---
---API
---
-
----Silently create new api entries pointing legacy functions to current
-function M.api_map(api)
-  api.config = api.config or {}
-  api.config.mappings = api.config.mappings or {}
-  api.config.mappings.get_keymap = api.map.keymap.current
-  api.config.mappings.get_keymap_default = api.map.keymap.default
-  api.config.mappings.default_on_attach = api.map.on_attach.default
-
-  api.live_filter = api.live_filter or {}
-  api.live_filter.start = api.filter.live.start
-  api.live_filter.clear = api.filter.live.clear
-
-  api.tree = api.tree or {}
-  api.tree.toggle_enable_filters = api.filter.toggle
-  api.tree.toggle_gitignore_filter = api.filter.git.ignored.toggle
-  api.tree.toggle_git_clean_filter = api.filter.git.clean.toggle
-  api.tree.toggle_no_buffer_filter = api.filter.no_buffer.toggle
-  api.tree.toggle_custom_filter = api.filter.custom.toggle
-  api.tree.toggle_hidden_filter = api.filter.dotfiles.toggle
-  api.tree.toggle_no_bookmark_filter = api.filter.no_bookmark.toggle
-
-  api.diagnostics = api.diagnostics or {}
-  api.diagnostics.hi_test = api.health.hi_test
-end
-
 return M

scripts/gen_vimdoc_config.lua

@@ -2,6 +2,9 @@
 --Returned config is injected into the above.
 --See gen_vimdoc.sh
 
+--gen_vimdoc keys by filename:   -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua`
+--Hence we must ensure that filenames are unique within each nvim.gen_vimdoc.Config[]
+
 ---@class (exact) Src
 ---@field helptag string must be globally unique
 ---@field section string arbitrary
@@ -37,7 +40,7 @@ local srcs_config = {
 
   { helptag = "nvim-tree-config-default",             section = "Config: Default",             path = pre .. "_meta/config/default.lua", },
 
-  { helptag = "nvim-tree-api",                        section = "API Placeholder",             path = pre .. "api.lua", },
+  { helptag = "nvim-tree-api",                        section = "placeholder for next Config", path = pre .. "api.lua", },
 }
 
 ---@type Src[]
@@ -89,7 +92,7 @@ local function src_by_name(name, srcs)
   error(string.format("\n\nPath for lower, extension stripped file name='%s' not found in\nsrcs=%s\n", name, vim.inspect(srcs)))
 end
 
--- @type table<string,nvim.gen_vimdoc.Config>
+-- @type nvim.gen_vimdoc.Config[]
 return {
   -- Config
   {