docs(#3088): revert api.git refactor, provide deprecated api meta

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -1017,8 +1017,6 @@ continue to be available.
 
 `api.diagnostics.hi_test`                |nvim_tree.api.health.hi_test()|
 
-`api.git.reload`                         |nvim_tree.api.tree.reload_git()|
-
 `api.live_filter.start`                  |nvim_tree.api.filter.live.start()|
 `api.live_filter.clear`                  |nvim_tree.api.filter.live.clear()|
 
@@ -2371,6 +2369,7 @@ The API is separated into multiple modules:
 • |nvim-tree-api-events|
 • |nvim-tree-api-filter|
 • |nvim-tree-api-fs|
+• |nvim-tree-api-git|
 • |nvim-tree-api-health|
 • |nvim-tree-api-map|
 • |nvim-tree-api-marks|
@@ -2602,6 +2601,14 @@ trash({node})                                       *nvim_tree.api.fs.trash()*
       • {node}  (`nvim_tree.api.Node?`)
 
 
+==============================================================================
+API: git                                                   *nvim-tree-api-git*
+
+                               *nvim_tree.api._git.nvim_tree.api.git.reload()*
+nvim_tree.api.git.reload()
+    Update the git status of the entire tree.
+
+
 ==============================================================================
 API: health                                             *nvim-tree-api-health*
 
@@ -3131,9 +3138,6 @@ open({opts})                                       *nvim_tree.api.tree.open()*
 reload()                                         *nvim_tree.api.tree.reload()*
     Refresh the tree. Does nothing if closed.
 
-reload_git()                                 *nvim_tree.api.tree.reload_git()*
-    Update the git status of the entire tree.
-
 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.

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

@@ -0,0 +1,9 @@
+---@meta
+local nvim_tree = { api = { git = {  } } }
+
+---
+---Update the git status of the entire tree.
+---
+function nvim_tree.api.git.reload() end
+
+return nvim_tree.api.config

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

@@ -228,9 +228,4 @@ function nvim_tree.api.tree.winid(opts) end
 ---[tab-ID] 0 or nil for current.
 ---@field tabpage? integer
 
----
----Update the git status of the entire tree.
----
-function nvim_tree.api.tree.reload_git() end
-
 return nvim_tree.api.tree

lua/nvim-tree/api.lua

@@ -11,6 +11,7 @@ local api = {}
 ---- [nvim-tree-api-events]
 ---- [nvim-tree-api-filter]
 ---- [nvim-tree-api-fs]
+---- [nvim-tree-api-git]
 ---- [nvim-tree-api-health]
 ---- [nvim-tree-api-map]
 ---- [nvim-tree-api-marks]
@@ -69,6 +70,7 @@ local api = {}
 ---@field dir? table<"direct" | "indirect", nvim_tree.git.XY[]> direct inclusive-or indirect status
 
 
+-- TODO #3088 add nvim_tree.api class
 
 --
 -- Load the (empty) meta definitions
@@ -77,13 +79,20 @@ api.commands = require("nvim-tree._meta.api.commands")
 api.events = require("nvim-tree._meta.api.events")
 api.filter = require("nvim-tree._meta.api.filter")
 api.fs = require("nvim-tree._meta.api.fs")
+api.git = require("nvim-tree._meta.api._git")
 api.health = require("nvim-tree._meta.api.health")
 api.map = require("nvim-tree._meta.api.map")
 api.marks = require("nvim-tree._meta.api.marks")
 api.node = require("nvim-tree._meta.api.node")
 api.tree = require("nvim-tree._meta.api.tree")
 
 
+---
+---@nodoc
+---Legacy meta definitions
+---
+api = require("nvim-tree.legacy").api_meta(api)
+
 
 --
 -- Map before-setup implementations, most throw an error notification "nvim-tree setup not called".

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

@@ -258,5 +258,5 @@ return function(api)
   hydrate_post(api)
 
   -- (Re)hydrate any legacy by mapping to function set above
-  require("nvim-tree.legacy").map_api(api)
+  require("nvim-tree.legacy").api_map(api)
 end

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

@@ -30,7 +30,6 @@ local function hydrate_error(t)
 end
 
 ---Hydrate implementations that may be called pre setup
----@param api table
 local function hydrate_pre(api)
   --
   -- Essential
@@ -66,7 +65,6 @@ local function hydrate_pre(api)
 end
 
 ---Hydrate api
----@param api table
 return function(api)
   -- Default: error
   hydrate_error(api)
@@ -75,5 +73,5 @@ return function(api)
   hydrate_pre(api)
 
   -- Hydrate any legacy by mapping to function set above
-  require("nvim-tree.legacy").map_api(api)
+  require("nvim-tree.legacy").api_map(api)
 end

lua/nvim-tree/legacy.lua

@@ -163,18 +163,14 @@ end
 --API
 --
 
----Create new api entries pointing legacy functions to current
----@param api table
-function M.map_api(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.git = api.git or {}
-  api.git.reload = api.tree.reload_git
-
   api.live_filter = api.live_filter or {}
   api.live_filter.start = api.filter.live.start
   api.live_filter.clear = api.filter.live.clear
@@ -192,4 +188,54 @@ function M.map_api(api)
   api.diagnostics.hi_test = api.health.hi_test
 end
 
+---Add meta definitions for deprecated API
+function M.api_meta(api)
+  ---@deprecated nvim_tree.api.filter.toggle
+  function api.tree.toggle_enable_filters() end
+
+  ---@deprecated nvim_tree.api.filter.git.ignored.toggle
+  function api.tree.toggle_gitignore_filter() end
+
+  ---@deprecated nvim_tree.api.filter.git.clean.toggle
+  function api.tree.toggle_git_clean_filter() end
+
+  ---@deprecated nvim_tree.api.filter.no_buffer.toggle
+  function api.tree.toggle_no_buffer_filter() end
+
+  ---@deprecated nvim_tree.api.filter.custom.toggle
+  function api.tree.toggle_custom_filter() end
+
+  ---@deprecated nvim_tree.api.filter.dotfiles.toggle
+  function api.tree.toggle_hidden_filter() end
+
+  ---@deprecated nvim_tree.api.filter.no_bookmark.toggle
+  function api.tree.toggle_no_bookmark_filter() end
+
+  api.config = { mappings = {} }
+
+  ---@deprecated nvim_tree.api.map.keymap.current
+  function api.config.mappings.get_keymap() end
+
+  ---@deprecated nvim_tree.api.map.keymap.default
+  function api.config.mappings.get_keymap_default() end
+
+  ---@deprecated nvim_tree.api.map.on_attach.default
+  function api.config.mappings.default_on_attach(_) end
+
+  api.live_filter = {}
+
+  ---@deprecated nvim_tree.api.filter.live.start
+  function api.live_filter.start() end
+
+  ---@deprecated nvim_tree.api.filter.live.clear
+  function api.live_filter.clear() end
+
+  api.diagnostics = {}
+
+  ---@deprecated nvim_tree.api.health.hi_test
+  function api.diagnostics.hi_test() end
+
+  return api
+end
+
 return M

scripts/gen_vimdoc_config.lua

@@ -44,6 +44,8 @@ local srcs = {
   { helptag = "nvim-tree-api-events",                 section = "API: events",                 path = "./lua/nvim_tree/_meta/api/events.lua", },
   { helptag = "nvim-tree-api-filter",                 section = "API: filter",                 path = "./lua/nvim_tree/_meta/api/filter.lua", },
   { helptag = "nvim-tree-api-fs",                     section = "API: fs",                     path = "./lua/nvim_tree/_meta/api/fs.lua", },
+  -- TODO #3088 come up with a solution to avoid filename clashes
+  { helptag = "nvim-tree-api-git",                    section = "API: git",                    path = "./lua/nvim_tree/_meta/api/_git.lua", },
   { helptag = "nvim-tree-api-health",                 section = "API: health",                 path = "./lua/nvim_tree/_meta/api/health.lua", },
   { helptag = "nvim-tree-api-map",                    section = "API: map",                    path = "./lua/nvim_tree/_meta/api/map.lua", },
   { helptag = "nvim-tree-api-marks",                  section = "API: marks",                  path = "./lua/nvim_tree/_meta/api/marks.lua", },
@@ -101,10 +103,13 @@ local config = {
 
         -- remove the API prefix from the left aligned function name
         -- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
+
+        -- TODO #3088 come up with a solution to avoid filename clashes
+        ---@diagnostic disable-next-line: unused-local
         local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
-        if (replaced ~= 1) then
-          error(string.format("function name does not start with module: %s", vim.inspect(fun)))
-        end
+        -- if (replaced ~= 1) then
+        --   error(string.format("function name does not start with module: %s", vim.inspect(fun)))
+        -- end
 
         print(string.format("fn_xform name: %s -> %s", fun.name, name))