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.

11 files changed, 205 insertions, 126 deletions

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 6c27e4775f..ba16943979 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -372,7 +372,8 @@ Use existing common {verb} names (actions) if possible:
     - create:       Creates a new (non-trivial) thing (TODO: rename to "def"?)
     - del:          Deletes a thing (or group of things)
     - detach:       Dispose attached listener (TODO: rename to "un"?)
-    - enable:       Enables/disables functionality.
+    - enable:       Enables/disables functionality. Signature should be
+                    `enable(enable?:boolean, filter?:table)`.
     - eval:         Evaluates an expression
     - exec:         Executes code
     - fmt:          Formats
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 1826cc4c08..437778574d 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -367,13 +367,6 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
       • {user_data}?  (`any`) arbitrary data plugins can add
       • {namespace}?  (`integer`)
 
-*vim.diagnostic.Filter*
-    Extends: |vim.diagnostic.Opts|
-
-
-    Fields: ~
-      • {ns_id}?  (`integer`) Namespace
-
 *vim.diagnostic.GetOpts*
     A table with the following keys:
 
@@ -623,20 +616,20 @@ count({bufnr}, {opts})                                *vim.diagnostic.count()*
         (`table`) Table with actually present severity values as keys (see
         |diagnostic-severity|) and integer counts as values.
 
-enable({bufnr}, {enable}, {opts})                    *vim.diagnostic.enable()*
+enable({enable}, {filter})                           *vim.diagnostic.enable()*
     Enables or disables diagnostics.
 
     To "toggle", pass the inverse of `is_enabled()`: >lua
-        vim.diagnostic.enable(0, not vim.diagnostic.is_enabled())
+        vim.diagnostic.enable(not vim.diagnostic.is_enabled())
 <
 
     Parameters: ~
-      • {bufnr}   (`integer?`) Buffer number, or 0 for current buffer, or
-                  `nil` for all buffers.
       • {enable}  (`boolean?`) true/nil to enable, false to disable
-      • {opts}    (`vim.diagnostic.Filter?`) Filter by these opts, or `nil`
-                  for all. Only `ns_id` is supported, currently. See
-                  |vim.diagnostic.Filter|.
+      • {filter}  (`table?`) Optional filters |kwargs|, or `nil` for all.
+                  • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for
+                    all.
+                  • {bufnr}? (`integer`) Buffer number, or 0 for current
+                    buffer, or `nil` for all buffers.
 
 fromqflist({list})                               *vim.diagnostic.fromqflist()*
     Convert a list of quickfix items to a list of diagnostics.
@@ -745,16 +738,18 @@ hide({namespace}, {bufnr})                             *vim.diagnostic.hide()*
       • {bufnr}      (`integer?`) Buffer number, or 0 for current buffer. When
                      omitted, hide diagnostics in all buffers.
 
-is_enabled({bufnr}, {namespace})                 *vim.diagnostic.is_enabled()*
+is_enabled({filter})                             *vim.diagnostic.is_enabled()*
     Check whether diagnostics are enabled.
 
     Note: ~
       • This API is pre-release (unstable).
 
     Parameters: ~
-      • {bufnr}      (`integer?`) Buffer number, or 0 for current buffer.
-      • {namespace}  (`integer?`) Diagnostic namespace, or `nil` for all
-                     diagnostics in {bufnr}.
+      • {filter}  (`table?`) Optional filters |kwargs|, or `nil` for all.
+                  • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for
+                    all.
+                  • {bufnr}? (`integer`) Buffer number, or 0 for current
+                    buffer, or `nil` for all buffers.
 
     Return: ~
         (`boolean`)
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 0ca5240da0..df85b7a2a9 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1588,19 +1588,21 @@ save({lenses}, {bufnr}, {client_id})                 *vim.lsp.codelens.save()*
 ==============================================================================
 Lua module: vim.lsp.inlay_hint                                *lsp-inlay_hint*
 
-enable({bufnr}, {enable})                        *vim.lsp.inlay_hint.enable()*
+enable({enable}, {filter})                       *vim.lsp.inlay_hint.enable()*
     Enables or disables inlay hints for a buffer.
 
     To "toggle", pass the inverse of `is_enabled()`: >lua
-        vim.lsp.inlay_hint.enable(0, not vim.lsp.inlay_hint.is_enabled())
+        vim.lsp.inlay_hint.enable(not vim.lsp.inlay_hint.is_enabled())
 <
 
     Note: ~
       • This API is pre-release (unstable).
 
     Parameters: ~
-      • {bufnr}   (`integer?`) Buffer handle, or 0 or nil for current
       • {enable}  (`boolean?`) true/nil to enable, false to disable
+      • {filter}  (`table?`) Optional filters |kwargs|, or `nil` for all.
+                  • {bufnr} (`integer?`) Buffer number, or 0/nil for current
+                    buffer.
 
 get({filter})                                       *vim.lsp.inlay_hint.get()*
     Get the list of inlay hints, (optionally) restricted by buffer or range.
@@ -1639,7 +1641,7 @@ is_enabled({bufnr})                          *vim.lsp.inlay_hint.is_enabled()*
       • This API is pre-release (unstable).
 
     Parameters: ~
-      • {bufnr}  (`integer?`) Buffer handle, or 0 or nil for current
+      • {bufnr}  (`integer?`) Buffer handle, or 0 for current
 
     Return: ~
         (`boolean`)
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 8d51d9d849..e580d5a2b7 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -149,6 +149,10 @@ unreleased features on Nvim HEAD.
 • Removed `vim.treesitter.foldtext` as transparent foldtext is now supported
   https://github.com/neovim/neovim/pull/20750
 
+• Changed the signature of `vim.lsp.inlay_hint.enable()`.
+
+• Changed the signature of `vim.diagnostic.enable()`.
+
 ==============================================================================
 NEW FEATURES                                                    *news-features*
 
@@ -529,6 +533,7 @@ release.
 • vim.diagnostic functions:
   - |vim.diagnostic.disable()|
   - |vim.diagnostic.is_disabled()|
+  - Legacy signature: `vim.diagnostic.enable(buf:number, namespace:number)`
 
 • vim.lsp functions:
   - |vim.lsp.util.get_progress_messages()|	Use |vim.lsp.status()| instead.
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index a40b298a37..2f6057c1f8 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -1049,10 +1049,11 @@ function vim.deprecate(name, alternative, version, plugin, backtrace)
     plugin = { plugin, 'string', true },
   }
   plugin = plugin or 'Nvim'
+  local will_be_removed = 'will be removed'
 
   -- Only issue warning if feature is hard-deprecated as specified by MAINTAIN.md.
-  -- e.g., when planned to be removed in version = '0.12' (soft-deprecated since 0.10-dev),
-  -- show warnings since 0.11, including 0.11-dev (hard_deprecated_since = 0.11-dev).
+  -- Example: if removal_version is 0.12 (soft-deprecated since 0.10-dev), show warnings starting at
+  -- 0.11, including 0.11-dev (hard_deprecated_since = 0.11-dev).
   if plugin == 'Nvim' then
     local current_version = vim.version() ---@type vim.Version
     local removal_version = assert(vim.version.parse(version))
@@ -1075,14 +1076,17 @@ function vim.deprecate(name, alternative, version, plugin, backtrace)
 
     if not is_hard_deprecated then
       return
+    elseif current_version >= removal_version then
+      will_be_removed = 'was removed'
     end
   end
 
   local msg = ('%s is deprecated'):format(name)
   msg = alternative and ('%s, use %s instead.'):format(msg, alternative) or (msg .. '.')
-  msg = ('%s%s\nThis feature will be removed in %s version %s'):format(
+  msg = ('%s%s\nFeature %s in %s %s'):format(
     msg,
     (plugin == 'Nvim' and ' :help deprecated' or ''),
+    will_be_removed,
     plugin,
     version
   )
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index 4fcbfa7507..6233bb7058 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -239,8 +239,16 @@ local M = {}
 --- whole line the sign is placed in.
 --- @field linehl? table<vim.diagnostic.Severity,string>
 
---- @class vim.diagnostic.Filter : vim.diagnostic.Opts
---- @field ns_id? integer Namespace
+-- TODO: inherit from `vim.diagnostic.Opts`, implement its fields.
+--- Optional filters |kwargs|, or `nil` for all.
+--- @class vim.diagnostic.Filter
+--- @inlinedoc
+---
+--- Diagnostic namespace, or `nil` for all.
+--- @field ns_id? integer
+---
+--- Buffer number, or 0 for current buffer, or `nil` for all buffers.
+--- @field bufnr? integer
 
 --- @nodoc
 --- @enum vim.diagnostic.Severity
@@ -1522,18 +1530,21 @@ end
 
 --- Check whether diagnostics are enabled.
 ---
---- @param bufnr integer? Buffer number, or 0 for current buffer.
---- @param namespace integer? Diagnostic namespace, or `nil` for all diagnostics in {bufnr}.
+--- @param filter vim.diagnostic.Filter?
 --- @return boolean
 --- @since 12
-function M.is_enabled(bufnr, namespace)
-  bufnr = get_bufnr(bufnr)
-  if namespace and M.get_namespace(namespace).disabled then
+function M.is_enabled(filter)
+  filter = filter or {}
+  if filter.ns_id and M.get_namespace(filter.ns_id).disabled then
     return false
+  elseif filter.bufnr == nil then
+    -- See enable() logic.
+    return vim.tbl_isempty(diagnostic_disabled) and not diagnostic_disabled[1]
   end
 
+  local bufnr = get_bufnr(filter.bufnr)
   if type(diagnostic_disabled[bufnr]) == 'table' then
-    return not diagnostic_disabled[bufnr][namespace]
+    return not diagnostic_disabled[bufnr][filter.ns_id]
   end
 
   return diagnostic_disabled[bufnr] == nil
@@ -1542,7 +1553,7 @@ end
 --- @deprecated use `vim.diagnostic.is_enabled()`
 function M.is_disabled(bufnr, namespace)
   vim.deprecate('vim.diagnostic.is_disabled()', 'vim.diagnostic.is_enabled()', '0.12', nil, false)
-  return not M.is_enabled(bufnr, namespace)
+  return not M.is_enabled { bufnr = bufnr or 0, ns_id = namespace }
 end
 
 --- Display diagnostics for the given namespace and buffer.
@@ -1588,7 +1599,7 @@ function M.show(namespace, bufnr, diagnostics, opts)
     return
   end
 
-  if not M.is_enabled(bufnr, namespace) then
+  if not M.is_enabled { bufnr = bufnr or 0, ns_id = namespace } then
     return
   end
 
@@ -1934,12 +1945,12 @@ end
 function M.disable(bufnr, namespace)
   vim.deprecate(
     'vim.diagnostic.disable()',
-    'vim.diagnostic.enabled(…, false)',
+    'vim.diagnostic.enabled(false, …)',
     '0.12',
     nil,
     false
   )
-  M.enable(bufnr, false, { ns_id = namespace })
+  M.enable(false, { bufnr = bufnr, ns_id = namespace })
 end
 
 --- Enables or disables diagnostics.
@@ -1947,53 +1958,49 @@ end
 --- To "toggle", pass the inverse of `is_enabled()`:
 ---
 --- ```lua
---- vim.diagnostic.enable(0, not vim.diagnostic.is_enabled())
+--- vim.diagnostic.enable(not vim.diagnostic.is_enabled())
 --- ```
 ---
---- @param bufnr integer? Buffer number, or 0 for current buffer, or `nil` for all buffers.
 --- @param enable (boolean|nil) true/nil to enable, false to disable
---- @param opts vim.diagnostic.Filter? Filter by these opts, or `nil` for all. Only `ns_id` is
---- supported, currently.
-function M.enable(bufnr, enable, opts)
-  opts = opts or {}
-  if type(enable) == 'number' then
-    -- Legacy signature.
+--- @param filter vim.diagnostic.Filter?
+function M.enable(enable, filter)
+  -- Deprecated signature. Drop this in 0.12
+  local legacy = (enable or filter)
+    and vim.tbl_contains({ 'number', 'nil' }, type(enable))
+    and vim.tbl_contains({ 'number', 'nil' }, type(filter))
+
+  if legacy then
     vim.deprecate(
-      'vim.diagnostic.enable(buf:number, namespace)',
-      'vim.diagnostic.enable(buf:number, enable:boolean, opts)',
+      'vim.diagnostic.enable(buf:number, namespace:number)',
+      'vim.diagnostic.enable(enable:boolean, filter:table)',
       '0.12',
       nil,
       false
     )
-    opts.ns_id = enable
+
+    vim.validate({
+      enable = { enable, 'n', true }, -- Legacy `bufnr` arg.
+      filter = { filter, 'n', true }, -- Legacy `namespace` arg.
+    })
+
+    local ns_id = type(filter) == 'number' and filter or nil
+    filter = {}
+    filter.ns_id = ns_id
+    filter.bufnr = type(enable) == 'number' and enable or nil
     enable = true
+  else
+    filter = filter or {}
+    vim.validate({
+      enable = { enable, 'b', true },
+      filter = { filter, 't', true },
+    })
   end
-  vim.validate({
-    bufnr = { bufnr, 'n', true },
-    enable = {
-      enable,
-      function(o)
-        return o == nil or type(o) == 'boolean' or type(o) == 'number'
-      end,
-      'boolean or number (deprecated)',
-    },
-    opts = {
-      opts,
-      function(o)
-        return o == nil
-          or (
-            type(o) == 'table'
-            -- TODO(justinmk): support other `vim.diagnostic.Filter` fields.
-            and (vim.tbl_isempty(o) or vim.deep_equal(vim.tbl_keys(o), { 'ns_id' }))
-          )
-      end,
-      'vim.diagnostic.Filter table (only ns_id is supported currently)',
-    },
-  })
+
   enable = enable == nil and true or enable
+  local bufnr = filter.bufnr
 
   if bufnr == nil then
-    if opts.ns_id == nil then
+    if filter.ns_id == nil then
       diagnostic_disabled = (
         enable
           -- Enable everything by setting diagnostic_disabled to an empty table.
@@ -2007,12 +2014,12 @@ function M.enable(bufnr, enable, opts)
         })
       )
     else
-      local ns = M.get_namespace(opts.ns_id)
+      local ns = M.get_namespace(filter.ns_id)
       ns.disabled = not enable
     end
   else
     bufnr = get_bufnr(bufnr)
-    if opts.ns_id == nil then
+    if filter.ns_id == nil then
       diagnostic_disabled[bufnr] = (not enable) and true or nil
     else
       if type(diagnostic_disabled[bufnr]) ~= 'table' then
@@ -2022,14 +2029,14 @@ function M.enable(bufnr, enable, opts)
           diagnostic_disabled[bufnr] = {}
         end
       end
-      diagnostic_disabled[bufnr][opts.ns_id] = (not enable) and true or nil
+      diagnostic_disabled[bufnr][filter.ns_id] = (not enable) and true or nil
     end
   end
 
   if enable then
-    M.show(opts.ns_id, bufnr)
+    M.show(filter.ns_id, bufnr)
   else
-    M.hide(opts.ns_id, bufnr)
+    M.hide(filter.ns_id, bufnr)
   end
 end
 
diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua
index ec676ea97f..6305f82efb 100644
--- a/runtime/lua/vim/lsp/inlay_hint.lua
+++ b/runtime/lua/vim/lsp/inlay_hint.lua
@@ -349,7 +349,7 @@ api.nvim_set_decoration_provider(namespace, {
   end,
 })
 
---- @param bufnr (integer|nil) Buffer handle, or 0 or nil for current
+--- @param bufnr (integer|nil) Buffer handle, or 0 for current
 --- @return boolean
 --- @since 12
 function M.is_enabled(bufnr)
@@ -360,23 +360,39 @@ function M.is_enabled(bufnr)
   return bufstates[bufnr] and bufstates[bufnr].enabled or false
 end
 
+--- Optional filters |kwargs|, or `nil` for all.
+--- @class vim.lsp.inlay_hint.enable.Filter
+--- @inlinedoc
+--- Buffer number, or 0/nil for current buffer.
+--- @field bufnr integer?
+
 --- Enables or disables inlay hints for a buffer.
 ---
 --- To "toggle", pass the inverse of `is_enabled()`:
 ---
 --- ```lua
---- vim.lsp.inlay_hint.enable(0, not vim.lsp.inlay_hint.is_enabled())
+--- vim.lsp.inlay_hint.enable(not vim.lsp.inlay_hint.is_enabled())
 --- ```
 ---
---- @param bufnr (integer|nil) Buffer handle, or 0 or nil for current
 --- @param enable (boolean|nil) true/nil to enable, false to disable
+--- @param filter vim.lsp.inlay_hint.enable.Filter?
 --- @since 12
-function M.enable(bufnr, enable)
-  vim.validate({ enable = { enable, 'boolean', true }, bufnr = { bufnr, 'number', true } })
+function M.enable(enable, filter)
+  if type(enable) == 'number' or type(filter) == 'boolean' then
+    vim.deprecate(
+      'vim.lsp.inlay_hint.enable(bufnr:number, enable:boolean)',
+      'vim.diagnostic.enable(enable:boolean, filter:table)',
+      '0.10-dev'
+    )
+    error('see :help vim.lsp.inlay_hint.enable() for updated parameters')
+  end
+
+  vim.validate({ enable = { enable, 'boolean', true }, filter = { filter, 'table', true } })
+  filter = filter or {}
   if enable == false then
-    _disable(bufnr)
+    _disable(filter.bufnr)
   else
-    _enable(bufnr)
+    _enable(filter.bufnr)
   end
 end
 
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