Merge #28227 feat(diagnostic): is_enabled, enable(…, enable:boolean)

5 files changed, 46 insertions, 23 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 5ac4ad4ce2..1b57f34896 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -80,12 +80,15 @@ HIGHLIGHTS
 - *hl-VertSplit*	Use |hl-WinSeparator| instead.
 
 LSP DIAGNOSTICS
+- *vim.diagnostic.disable()*		Use |vim.diagnostic.enable()|
+- *vim.diagnostic.is_disabled()*	Use |vim.diagnostic.is_enabled()|
+
 For each of the functions below, use the corresponding function in
 |vim.diagnostic| instead (unless otherwise noted). For example, use
 |vim.diagnostic.get()| instead of |vim.lsp.diagnostic.get()|.
 
 - *vim.lsp.diagnostic.clear()*		Use |vim.diagnostic.hide()| instead.
-- *vim.lsp.diagnostic.disable()*
+- *vim.lsp.diagnostic.disable()*          Use |vim.diagnostic.enable()| instead.
 - *vim.lsp.diagnostic.display()*	Use |vim.diagnostic.show()| instead.
 - *vim.lsp.diagnostic.enable()*
 - *vim.lsp.diagnostic.get()*
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 767f46ad1e..6c27e4775f 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -372,20 +372,25 @@ 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.
     - eval:         Evaluates an expression
     - exec:         Executes code
     - fmt:          Formats
     - get:          Gets things (often by a query)
     - inspect:      Presents a high-level, often interactive, view
+    - is_enabled:   Checks if functionality is enabled.
     - open:         Opens something (a buffer, window, …)
     - parse:        Parses something into a structured form
     - set:          Sets a thing (or group of things)
     - try_{verb}:   Best-effort operation, failure returns null or error obj
 
 Do NOT use these deprecated verbs:
+    - disable:      Prefer `enable(enable: boolean)`.
+    - is_disabled:  Prefer `is_enabled()`.
     - list:         Redundant with "get"
-    - show:         Redundant with "print", "echo"
     - notify:       Redundant with "print", "echo"
+    - show:         Redundant with "print", "echo"
+    - toggle:       Prefer `enable(not is_enabled())`.
 
 Use consistent names for {noun} (nouns) in API functions: buffer is called
 "buf" everywhere, not "buffer" in some places and "buf" in others.
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index a9172119d0..1826cc4c08 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -367,6 +367,13 @@ 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:
 
@@ -616,23 +623,20 @@ count({bufnr}, {opts})                                *vim.diagnostic.count()*
         (`table`) Table with actually present severity values as keys (see
         |diagnostic-severity|) and integer counts as values.
 
-disable({bufnr}, {namespace})                       *vim.diagnostic.disable()*
-    Disable diagnostics in the given buffer.
-
-    Parameters: ~
-      • {bufnr}      (`integer?`) Buffer number, or 0 for current buffer. When
-                     omitted, disable diagnostics in all buffers.
-      • {namespace}  (`integer?`) Only disable diagnostics for the given
-                     namespace.
+enable({bufnr}, {enable}, {opts})                    *vim.diagnostic.enable()*
+    Enables or disables diagnostics.
 
-enable({bufnr}, {namespace})                         *vim.diagnostic.enable()*
-    Enable diagnostics in the given buffer.
+    To "toggle", pass the inverse of `is_enabled()`: >lua
+        vim.diagnostic.enable(0, not vim.diagnostic.is_enabled())
+<
 
     Parameters: ~
-      • {bufnr}      (`integer?`) Buffer number, or 0 for current buffer. When
-                     omitted, enable diagnostics in all buffers.
-      • {namespace}  (`integer?`) Only enable diagnostics for the given
-                     namespace.
+      • {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|.
 
 fromqflist({list})                               *vim.diagnostic.fromqflist()*
     Convert a list of quickfix items to a list of diagnostics.
@@ -733,7 +737,7 @@ hide({namespace}, {bufnr})                             *vim.diagnostic.hide()*
     diagnostics, use |vim.diagnostic.reset()|.
 
     To hide diagnostics and prevent them from re-displaying, use
-    |vim.diagnostic.disable()|.
+    |vim.diagnostic.enable()|.
 
     Parameters: ~
       • {namespace}  (`integer?`) Diagnostic namespace. When omitted, hide
@@ -741,14 +745,16 @@ hide({namespace}, {bufnr})                             *vim.diagnostic.hide()*
       • {bufnr}      (`integer?`) Buffer number, or 0 for current buffer. When
                      omitted, hide diagnostics in all buffers.
 
-is_disabled({bufnr}, {namespace})               *vim.diagnostic.is_disabled()*
-    Check whether diagnostics are disabled in a given buffer.
+is_enabled({bufnr}, {namespace})                 *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. When omitted, checks
-                     if all diagnostics are disabled in {bufnr}. Otherwise,
-                     only checks if diagnostics from {namespace} are disabled.
+      • {namespace}  (`integer?`) Diagnostic namespace, or `nil` for all
+                     diagnostics in {bufnr}.
 
     Return: ~
         (`boolean`)
diff --git a/runtime/doc/news-0.9.txt b/runtime/doc/news-0.9.txt
index 789bc9e0bc..f1f3ac6954 100644
--- a/runtime/doc/news-0.9.txt
+++ b/runtime/doc/news-0.9.txt
@@ -162,7 +162,7 @@ The following new APIs or features were added.
 • |vim.diagnostic| now supports LSP DiagnosticsTag.
   See: https://microsoft.github.io/language-server-protocol/specification/#diagnosticTag
 
-• |vim.diagnostic.is_disabled()| checks if diagnostics are disabled in a given
+• vim.diagnostic.is_disabled() checks if diagnostics are disabled in a given
   buffer or namespace.
 
 • Treesitter captures can now be transformed by directives. This will allow
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index ae5f808a9c..d320db4e51 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -328,6 +328,8 @@ The following new APIs and features were added.
   |vim.diagnostic.get()| when only the number of diagnostics is needed, but
   not the diagnostics themselves.
 
+• Introduced |vim.diagnostic.is_enabled()|
+
 • |vim.deepcopy()| has a `noref` argument to avoid hashing table values.
 
 • Terminal buffers emit a |TermRequest| autocommand event when the child
@@ -419,6 +421,9 @@ The following changes to existing APIs or features add new behavior.
 • |vim.diagnostic.get()| and |vim.diagnostic.count()| accept multiple
   namespaces rather than just a single namespace.
 
+• |vim.diagnostic.enable()| gained new parameters, and the old signature is
+  deprecated.
+
 • Extmarks now fully support multi-line ranges, and a single extmark can be
   used to highlight a range of arbitrary length. The |nvim_buf_set_extmark()|
   API function already allowed you to define such ranges, but highlight regions
@@ -520,6 +525,10 @@ release.
   - |nvim_win_get_option()|	Use |nvim_get_option_value()| instead.
   - |nvim_win_set_option()|	Use |nvim_set_option_value()| instead.
 
+• vim.diagnostic functions:
+  - |vim.diagnostic.disable()|
+  - |vim.diagnostic.is_disabled()|
+
 • vim.lsp functions:
   - |vim.lsp.util.get_progress_messages()|	Use |vim.lsp.status()| instead.
   - |vim.lsp.get_active_clients()|		Use |vim.lsp.get_clients()| instead.