feat(lua): enable(enable:boolean, filter:table) #28374

Problem:
We need to establish a pattern for `enable()`.

Solution:
- First `enable()` parameter is always `enable:boolean`.
- Update `vim.diagnostic.enable()`
- Update `vim.lsp.inlay_hint.enable()`.
    - It was not released yet, so no deprecation is needed. But to help
      HEAD users, it will show an informative error.
- vim.deprecate():
    - Improve message when the "removal version" is a *current or older* version.

4 files changed, 91 insertions, 42 deletions

diff --git a/test/functional/lua/diagnostic_spec.lua b/test/functional/lua/diagnostic_spec.lua
index 1a87d159c7..31358a2226 100644
--- a/test/functional/lua/diagnostic_spec.lua
+++ b/test/functional/lua/diagnostic_spec.lua
@@ -329,7 +329,7 @@ describe('vim.diagnostic', function()
     eq(
       { 1, 1, 2, 0, 2 },
       exec_lua [[
-      vim.diagnostic.enable(diagnostic_bufnr, false, { ns_id = diagnostic_ns })
+      vim.diagnostic.enable(false, { bufnr = diagnostic_bufnr, ns_id = diagnostic_ns })
       return {
         count_diagnostics(diagnostic_bufnr, vim.diagnostic.severity.ERROR, diagnostic_ns),
         count_diagnostics(diagnostic_bufnr, vim.diagnostic.severity.WARN, other_ns),
@@ -344,7 +344,7 @@ describe('vim.diagnostic', function()
     eq(
       all_highlights,
       exec_lua([[
-      vim.diagnostic.enable(diagnostic_bufnr, true, { ns_id = diagnostic_ns })
+      vim.diagnostic.enable(true, { bufnr = diagnostic_bufnr, ns_id = diagnostic_ns })
       return {
         count_diagnostics(diagnostic_bufnr, vim.diagnostic.severity.ERROR, diagnostic_ns),
         count_diagnostics(diagnostic_bufnr, vim.diagnostic.severity.WARN, other_ns),
@@ -371,7 +371,7 @@ describe('vim.diagnostic', function()
       vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, ns_1_diags)
       vim.diagnostic.set(other_ns, diagnostic_bufnr, ns_2_diags)
 
-      vim.diagnostic.enable(diagnostic_bufnr, false, { ns_id = diagnostic_ns })
+      vim.diagnostic.enable(false, { bufnr = diagnostic_bufnr, ns_id = diagnostic_ns })
 
       return {
         count_extmarks(diagnostic_bufnr, diagnostic_ns),
@@ -383,8 +383,8 @@ describe('vim.diagnostic', function()
     eq(
       { 4, 0 },
       exec_lua [[
-      vim.diagnostic.enable(diagnostic_bufnr, true, { ns_id = diagnostic_ns })
-      vim.diagnostic.enable(diagnostic_bufnr, false, { ns_id = other_ns })
+      vim.diagnostic.enable(true, { bufnr = diagnostic_bufnr, ns_id = diagnostic_ns })
+      vim.diagnostic.enable(false, { bufnr = diagnostic_bufnr, ns_id = other_ns })
 
       return {
         count_extmarks(diagnostic_bufnr, diagnostic_ns),
@@ -478,6 +478,31 @@ describe('vim.diagnostic', function()
   end)
 
   describe('enable() and disable()', function()
+    it('validation', function()
+      matches('expected boolean, got table', pcall_err(exec_lua, [[vim.diagnostic.enable({})]]))
+      matches(
+        'filter: expected table, got string',
+        pcall_err(exec_lua, [[vim.diagnostic.enable(false, '')]])
+      )
+      matches(
+        'Invalid buffer id: 42',
+        pcall_err(exec_lua, [[vim.diagnostic.enable(true, { bufnr = 42 })]])
+      )
+      matches(
+        'expected boolean, got number',
+        pcall_err(exec_lua, [[vim.diagnostic.enable(42, {})]])
+      )
+      matches('expected boolean, got table', pcall_err(exec_lua, [[vim.diagnostic.enable({}, 42)]]))
+
+      -- Deprecated signature.
+      matches('Invalid buffer id: 42', pcall_err(exec_lua, [[vim.diagnostic.enable(42)]]))
+      -- Deprecated signature.
+      matches(
+        'namespace does not exist or is anonymous',
+        pcall_err(exec_lua, [[vim.diagnostic.enable(nil, 42)]])
+      )
+    end)
+
     it('without arguments', function()
       local result = exec_lua [[
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
@@ -500,7 +525,7 @@ describe('vim.diagnostic', function()
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
                              count_extmarks(diagnostic_bufnr, other_ns))
 
-        vim.diagnostic.enable(nil, false)
+        vim.diagnostic.enable(false)
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
                              count_extmarks(diagnostic_bufnr, other_ns))
@@ -561,19 +586,19 @@ describe('vim.diagnostic', function()
                              count_extmarks(diagnostic_bufnr, other_ns) +
                              count_extmarks(other_bufnr, diagnostic_ns))
 
-        vim.diagnostic.enable(diagnostic_bufnr, false)
+        vim.diagnostic.enable(false, { bufnr = diagnostic_bufnr })
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
                              count_extmarks(diagnostic_bufnr, other_ns) +
                              count_extmarks(other_bufnr, diagnostic_ns))
 
-        vim.diagnostic.enable(diagnostic_bufnr)
+        vim.diagnostic.enable(true, { bufnr = diagnostic_bufnr })
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
                              count_extmarks(diagnostic_bufnr, other_ns) +
                              count_extmarks(other_bufnr, diagnostic_ns))
 
-        vim.diagnostic.enable(other_bufnr, false)
+        vim.diagnostic.enable(false, { bufnr = other_bufnr })
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
                              count_extmarks(diagnostic_bufnr, other_ns) +
@@ -610,17 +635,17 @@ describe('vim.diagnostic', function()
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
                              count_extmarks(diagnostic_bufnr, other_ns))
 
-        vim.diagnostic.enable(nil, false, { ns_id = diagnostic_ns })
+        vim.diagnostic.enable(false, { ns_id = diagnostic_ns })
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
                              count_extmarks(diagnostic_bufnr, other_ns))
 
-        vim.diagnostic.enable(nil, true, { ns_id = diagnostic_ns })
+        vim.diagnostic.enable(true, { ns_id = diagnostic_ns })
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
                              count_extmarks(diagnostic_bufnr, other_ns))
 
-        vim.diagnostic.enable(nil, false, { ns_id = other_ns })
+        vim.diagnostic.enable(false, { ns_id = other_ns })
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
                              count_extmarks(diagnostic_bufnr, other_ns))
@@ -669,7 +694,7 @@ describe('vim.diagnostic', function()
         if legacy then
           vim.diagnostic.disable(diagnostic_bufnr, diagnostic_ns)
         else
-          vim.diagnostic.enable(diagnostic_bufnr, false, { ns_id = diagnostic_ns })
+          vim.diagnostic.enable(false, { bufnr = diagnostic_bufnr, ns_id = diagnostic_ns })
         end
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
@@ -679,7 +704,7 @@ describe('vim.diagnostic', function()
         if legacy then
           vim.diagnostic.disable(diagnostic_bufnr, other_ns)
         else
-          vim.diagnostic.enable(diagnostic_bufnr, false, { ns_id = other_ns })
+          vim.diagnostic.enable(false, { bufnr = diagnostic_bufnr, ns_id = other_ns })
         end
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
@@ -689,7 +714,7 @@ describe('vim.diagnostic', function()
         if legacy then
           vim.diagnostic.enable(diagnostic_bufnr, diagnostic_ns)
         else
-          vim.diagnostic.enable(diagnostic_bufnr, true, { ns_id = diagnostic_ns })
+          vim.diagnostic.enable(true, { bufnr = diagnostic_bufnr, ns_id = diagnostic_ns })
         end
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
@@ -701,7 +726,7 @@ describe('vim.diagnostic', function()
           vim.diagnostic.disable(other_bufnr, other_ns)
         else
           -- Should have no effect
-          vim.diagnostic.enable(other_bufnr, false, { ns_id = other_ns })
+          vim.diagnostic.enable(false, { bufnr = other_bufnr, ns_id = other_ns })
         end
 
         table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
@@ -1592,7 +1617,7 @@ describe('vim.diagnostic', function()
   end)
 
   describe('set()', function()
-    it('validates its arguments', function()
+    it('validation', function()
       matches(
         'expected a list of diagnostics',
         pcall_err(exec_lua, [[vim.diagnostic.set(1, 0, {lnum = 1, col = 2})]])
@@ -1779,7 +1804,7 @@ describe('vim.diagnostic', function()
       eq(
         0,
         exec_lua [[
-        vim.diagnostic.enable(diagnostic_bufnr, false, { ns_id = diagnostic_ns })
+        vim.diagnostic.enable(false, { bufnr = diagnostic_bufnr, ns_id = diagnostic_ns })
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, {
           make_error('Diagnostic From Server 1:1', 1, 1, 1, 1),
         })
@@ -1790,7 +1815,7 @@ describe('vim.diagnostic', function()
       eq(
         2,
         exec_lua [[
-        vim.diagnostic.enable(diagnostic_bufnr, true, { ns_id = diagnostic_ns })
+        vim.diagnostic.enable(true, { bufnr = diagnostic_bufnr, ns_id = diagnostic_ns })
         return count_extmarks(diagnostic_bufnr, diagnostic_ns)
       ]]
       )
@@ -2750,31 +2775,33 @@ describe('vim.diagnostic', function()
 
     it('is_enabled', function()
       eq(
-        { false, false, false, false },
+        { false, false, false, false, false },
         exec_lua [[
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, {
           make_error('Diagnostic #1', 1, 1, 1, 1),
         })
         vim.api.nvim_set_current_buf(diagnostic_bufnr)
-        vim.diagnostic.enable(nil, false)
+        vim.diagnostic.enable(false)
         return {
           vim.diagnostic.is_enabled(),
-          vim.diagnostic.is_enabled(diagnostic_bufnr),
-          vim.diagnostic.is_enabled(diagnostic_bufnr, diagnostic_ns),
-          vim.diagnostic.is_enabled(_, diagnostic_ns),
+          vim.diagnostic.is_enabled{ bufnr = 0 },
+          vim.diagnostic.is_enabled{ bufnr = diagnostic_bufnr },
+          vim.diagnostic.is_enabled{ bufnr = diagnostic_bufnr, ns_id = diagnostic_ns },
+          vim.diagnostic.is_enabled{ bufnr = 0, ns_id = diagnostic_ns },
         }
       ]]
       )
 
       eq(
-        { true, true, true, true },
+        { true, true, true, true, true },
         exec_lua [[
         vim.diagnostic.enable()
         return {
           vim.diagnostic.is_enabled(),
-          vim.diagnostic.is_enabled(diagnostic_bufnr),
-          vim.diagnostic.is_enabled(diagnostic_bufnr, diagnostic_ns),
-          vim.diagnostic.is_enabled(_, diagnostic_ns),
+          vim.diagnostic.is_enabled{ bufnr = 0 },
+          vim.diagnostic.is_enabled{ bufnr = diagnostic_bufnr },
+          vim.diagnostic.is_enabled{ bufnr = diagnostic_bufnr, ns_id = diagnostic_ns },
+          vim.diagnostic.is_enabled{ bufnr = 0, ns_id = diagnostic_ns },
         }
       ]]
       )
diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua
index 6fbac84d96..436ada4886 100644
--- a/test/functional/lua/vim_spec.lua
+++ b/test/functional/lua/vim_spec.lua
@@ -147,10 +147,13 @@ describe('lua stdlib', function()
       end)
 
       it('when plugin = nil', function()
+        local was_removed = (
+          vim.version.ge(current_version, '0.10') and 'was removed' or 'will be removed'
+        )
         eq(
-          dedent [[
+          dedent([[
             foo.bar() is deprecated, use zub.wooo{ok=yay} instead. :help deprecated
-            This feature will be removed in Nvim version 0.10]],
+            Feature %s in Nvim 0.10]]):format(was_removed),
           exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '0.10')
         )
         -- Same message, skipped.
@@ -166,7 +169,7 @@ describe('lua stdlib', function()
         eq(
           dedent [[
             foo.hard_dep() is deprecated, use vim.new_api() instead. :help deprecated
-            This feature will be removed in Nvim version 0.11]],
+            Feature will be removed in Nvim 0.11]],
           exec_lua('return vim.deprecate(...)', 'foo.hard_dep()', 'vim.new_api()', '0.11')
         )
 
@@ -174,7 +177,7 @@ describe('lua stdlib', function()
         eq(
           dedent [[
             foo.baz() is deprecated. :help deprecated
-            This feature will be removed in Nvim version 1.0]],
+            Feature will be removed in Nvim 1.0]],
           exec_lua [[ return vim.deprecate('foo.baz()', nil, '1.0') ]]
         )
       end)
@@ -184,7 +187,7 @@ describe('lua stdlib', function()
         eq(
           dedent [[
             foo.bar() is deprecated, use zub.wooo{ok=yay} instead.
-            This feature will be removed in my-plugin.nvim version 0.3.0]],
+            Feature will be removed in my-plugin.nvim 0.3.0]],
           exec_lua(
             'return vim.deprecate(...)',
             'foo.bar()',
@@ -199,7 +202,7 @@ describe('lua stdlib', function()
         eq(
           dedent [[
             foo.bar() is deprecated, use zub.wooo{ok=yay} instead.
-            This feature will be removed in my-plugin.nvim version 0.11.0]],
+            Feature will be removed in my-plugin.nvim 0.11.0]],
           exec_lua(
             'return vim.deprecate(...)',
             'foo.bar()',
diff --git a/test/functional/plugin/lsp/inlay_hint_spec.lua b/test/functional/plugin/lsp/inlay_hint_spec.lua
index 64c65b74c3..24c93fcbe0 100644
--- a/test/functional/plugin/lsp/inlay_hint_spec.lua
+++ b/test/functional/plugin/lsp/inlay_hint_spec.lua
@@ -84,7 +84,7 @@ before_each(function()
   )
 
   insert(text)
-  exec_lua([[vim.lsp.inlay_hint.enable(bufnr)]])
+  exec_lua([[vim.lsp.inlay_hint.enable(true, { bufnr = bufnr })]])
   screen:expect({ grid = grid_with_inlay_hints })
 end)
 
@@ -111,7 +111,7 @@ describe('vim.lsp.inlay_hint', function()
         }
       })
       client2 = vim.lsp.start({ name = 'dummy2', cmd = server2.cmd })
-      vim.lsp.inlay_hint.enable(bufnr)
+      vim.lsp.inlay_hint.enable(true, { bufnr = bufnr })
     ]])
 
     exec_lua([[ vim.lsp.stop_client(client2) ]])
@@ -119,17 +119,36 @@ describe('vim.lsp.inlay_hint', function()
   end)
 
   describe('enable()', function()
+    it('validation', function()
+      t.matches(
+        'enable: expected boolean, got table',
+        t.pcall_err(exec_lua, [[vim.lsp.inlay_hint.enable({}, { bufnr = bufnr })]])
+      )
+      t.matches(
+        'filter: expected table, got number',
+        t.pcall_err(exec_lua, [[vim.lsp.inlay_hint.enable(true, 42)]])
+      )
+
+      exec_lua [[vim.notify = function() end]]
+      t.matches(
+        'see %:help vim%.lsp%.inlay_hint%.enable',
+        t.pcall_err(exec_lua, [[vim.lsp.inlay_hint.enable(42)]])
+      )
+    end)
+
     it('clears/applies inlay hints when passed false/true/nil', function()
-      exec_lua([[vim.lsp.inlay_hint.enable(bufnr, false)]])
+      exec_lua([[vim.lsp.inlay_hint.enable(false, { bufnr = bufnr })]])
       screen:expect({ grid = grid_without_inlay_hints, unchanged = true })
 
-      exec_lua([[vim.lsp.inlay_hint.enable(bufnr, true)]])
+      exec_lua([[vim.lsp.inlay_hint.enable(true, { bufnr = bufnr })]])
       screen:expect({ grid = grid_with_inlay_hints, unchanged = true })
 
-      exec_lua([[vim.lsp.inlay_hint.enable(bufnr, not vim.lsp.inlay_hint.is_enabled(bufnr))]])
+      exec_lua(
+        [[vim.lsp.inlay_hint.enable(not vim.lsp.inlay_hint.is_enabled(bufnr), { bufnr = bufnr })]]
+      )
       screen:expect({ grid = grid_without_inlay_hints, unchanged = true })
 
-      exec_lua([[vim.lsp.inlay_hint.enable(bufnr)]])
+      exec_lua([[vim.lsp.inlay_hint.enable(true, { bufnr = bufnr })]])
       screen:expect({ grid = grid_with_inlay_hints, unchanged = true })
     end)
   end)
@@ -163,7 +182,7 @@ describe('vim.lsp.inlay_hint', function()
           }
         })
         client2 = vim.lsp.start({ name = 'dummy2', cmd = server2.cmd })
-        vim.lsp.inlay_hint.enable(bufnr)
+        vim.lsp.inlay_hint.enable(true, { bufnr = bufnr })
       ]],
         expected2
       )
diff --git a/test/functional/plugin/lsp_spec.lua b/test/functional/plugin/lsp_spec.lua
index feca31c01b..5b90e6de6c 100644
--- a/test/functional/plugin/lsp_spec.lua
+++ b/test/functional/plugin/lsp_spec.lua
@@ -1328,7 +1328,7 @@ describe('LSP', function()
         on_handler = function(err, result, ctx)
           if ctx.method == 'start' then
             exec_lua [[
-              vim.lsp.inlay_hint.enable(BUFFER)
+              vim.lsp.inlay_hint.enable(true, { bufnr = BUFFER })
             ]]
           end
           if ctx.method == 'textDocument/inlayHint' then