fix(lua): remove vim.loader.disable() #31344

Problem:
`vim.loader.disable` does not conform to `:help dev-name-common` and
`:help dev-patterns`.

Solution:
- Add `enable` parameter to `vim.loader.enable`
- Remove `vim.loader.disable`
- Note the change in `:help news-breaking-dev` (HEAD changes).
  - This is not a breaking change (except to "HEAD") because
    `vim.loader` is marked "experimental".

previous: 26765e8461c1ba1e9a351632212cf89900221781

4 files changed, 63 insertions, 46 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 4d4a51872a..cf53825c68 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2485,22 +2485,24 @@ vim.validate({name}, {value}, {validator}, {optional}, {message})
 ==============================================================================
 Lua module: vim.loader                                            *vim.loader*
 
-vim.loader.disable()                                    *vim.loader.disable()*
+vim.loader.enable({enable})                              *vim.loader.enable()*
     WARNING: This feature is experimental/unstable.
 
-    Disables the experimental Lua module loader:
-    • removes the loaders
-    • adds the default Nvim loader
+    Enables or disables the experimental Lua module loader:
 
-vim.loader.enable()                                      *vim.loader.enable()*
-    WARNING: This feature is experimental/unstable.
-
-    Enables the experimental Lua module loader:
-    • overrides loadfile
+    Enable (`enable=true`):
+    • overrides |loadfile()|
     • adds the Lua loader using the byte-compilation cache
     • adds the libs loader
     • removes the default Nvim loader
 
+    Disable (`enable=false`):
+    • removes the loaders
+    • adds the default Nvim loader
+
+    Parameters: ~
+      • {enable}  (`boolean?`) true/nil to enable, false to disable
+
 vim.loader.find({modname}, {opts})                         *vim.loader.find()*
     WARNING: This feature is experimental/unstable.
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 58ab7ef44c..9c69970400 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -11,13 +11,17 @@ For changes in the previous release, see |news-0.10|.
                                        Type |gO| to see the table of contents.
 
 ==============================================================================
-BREAKING CHANGES IN HEAD                                    *news-breaking-dev*
+BREAKING CHANGES IN HEAD OR EXPERIMENTAL                    *news-breaking-dev*
 
               ====== Remove this section before release. ======
 
 The following changes to UNRELEASED features were made during the development
 cycle (Nvim HEAD, the "master" branch).
 
+EXPERIMENTS
+
+• Removed `vim.loader.disable()`. Use `vim.loader.enable(false)` instead.
+
 OPTIONS
 
 • 'jumpoptions' flag "unload" has been renamed to "clean".
diff --git a/runtime/lua/vim/loader.lua b/runtime/lua/vim/loader.lua
index 0cce0ab21d..71d0188128 100644
--- a/runtime/lua/vim/loader.lua
+++ b/runtime/lua/vim/loader.lua
@@ -399,50 +399,51 @@ function M.reset(path)
   end
 end
 
---- Enables the experimental Lua module loader:
---- * overrides loadfile
+--- Enables or disables the experimental Lua module loader:
+---
+--- Enable (`enable=true`):
+--- * overrides |loadfile()|
 --- * adds the Lua loader using the byte-compilation cache
 --- * adds the libs loader
 --- * removes the default Nvim loader
 ---
---- @since 0
-function M.enable()
-  if M.enabled then
-    return
-  end
-  M.enabled = true
-  vim.fn.mkdir(vim.fn.fnamemodify(M.path, ':p'), 'p')
-  _G.loadfile = loadfile_cached
-  -- add Lua loader
-  table.insert(loaders, 2, loader_cached)
-  -- add libs loader
-  table.insert(loaders, 3, loader_lib_cached)
-  -- remove Nvim loader
-  for l, loader in ipairs(loaders) do
-    if loader == vim._load_package then
-      table.remove(loaders, l)
-      break
-    end
-  end
-end
-
---- Disables the experimental Lua module loader:
+--- Disable (`enable=false`):
 --- * removes the loaders
 --- * adds the default Nvim loader
 ---
 --- @since 0
-function M.disable()
-  if not M.enabled then
+---
+--- @param enable? (boolean) true/nil to enable, false to disable
+function M.enable(enable)
+  enable = enable == nil and true or enable
+  if enable == M.enabled then
     return
   end
-  M.enabled = false
-  _G.loadfile = _loadfile
-  for l, loader in ipairs(loaders) do
-    if loader == loader_cached or loader == loader_lib_cached then
-      table.remove(loaders, l)
+  M.enabled = enable
+
+  if enable then
+    vim.fn.mkdir(vim.fn.fnamemodify(M.path, ':p'), 'p')
+    _G.loadfile = loadfile_cached
+    -- add Lua loader
+    table.insert(loaders, 2, loader_cached)
+    -- add libs loader
+    table.insert(loaders, 3, loader_lib_cached)
+    -- remove Nvim loader
+    for l, loader in ipairs(loaders) do
+      if loader == vim._load_package then
+        table.remove(loaders, l)
+        break
+      end
+    end
+  else
+    _G.loadfile = _loadfile
+    for l, loader in ipairs(loaders) do
+      if loader == loader_cached or loader == loader_lib_cached then
+        table.remove(loaders, l)
+      end
     end
+    table.insert(loaders, 2, vim._load_package)
   end
-  table.insert(loaders, 2, vim._load_package)
 end
 
 --- Tracks the time spent in a function
diff --git a/test/functional/lua/loader_spec.lua b/test/functional/lua/loader_spec.lua
index 8508f2aa14..20d3a940b2 100644
--- a/test/functional/lua/loader_spec.lua
+++ b/test/functional/lua/loader_spec.lua
@@ -10,7 +10,17 @@ local eq = t.eq
 describe('vim.loader', function()
   before_each(clear)
 
-  it('can work in compatibility with --luamod-dev #27413', function()
+  it('can be disabled', function()
+    exec_lua(function()
+      local orig_loader = _G.loadfile
+      vim.loader.enable()
+      assert(orig_loader ~= _G.loadfile)
+      vim.loader.enable(false)
+      assert(orig_loader == _G.loadfile)
+    end)
+  end)
+
+  it('works with --luamod-dev #27413', function()
     clear({ args = { '--luamod-dev' } })
     exec_lua(function()
       vim.loader.enable()
@@ -31,7 +41,7 @@ describe('vim.loader', function()
     end)
   end)
 
-  it('handles changing files (#23027)', function()
+  it('handles changing files #23027', function()
     exec_lua(function()
       vim.loader.enable()
     end)
@@ -63,7 +73,7 @@ describe('vim.loader', function()
     )
   end)
 
-  it('handles % signs in modpath (#24491)', function()
+  it('handles % signs in modpath #24491', function()
     exec_lua [[
       vim.loader.enable()
     ]]
@@ -82,7 +92,7 @@ describe('vim.loader', function()
     eq(2, exec_lua('return loadfile(...)()', tmp2))
   end)
 
-  it('correct indent on error message (#29809)', function()
+  it('indents error message #29809', function()
     local errmsg = exec_lua [[
       vim.loader.enable()
       local _, errmsg = pcall(require, 'non_existent_module')