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, 26 insertions, 23 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.