feat(diagnostic): enable(…, opts)

Problem:
vim.diagnostic.enable() does not match the signature of vim.lsp.inlay_hint.enable()

Solution:
- Change the signature so that the first 2 args are (bufnr, enable).
- Introduce a 3rd `opts` arg.
    - Currently it only supports `opts.ns_id`.

3 files changed, 18 insertions, 7 deletions

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index a7373c84b3..6c27e4775f 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -372,11 +372,13 @@ 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)
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 1f3f1c80fe..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,7 +623,7 @@ 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}, {namespace}, {enable})               *vim.diagnostic.enable()*
+enable({bufnr}, {enable}, {opts})                    *vim.diagnostic.enable()*
     Enables or disables diagnostics.
 
     To "toggle", pass the inverse of `is_enabled()`: >lua
@@ -624,11 +631,12 @@ enable({bufnr}, {namespace}, {enable})               *vim.diagnostic.enable()*
 <
 
     Parameters: ~
-      • {bufnr}      (`integer?`) Buffer number, or 0 for current buffer, or
-                     `nil` for all buffers.
-      • {namespace}  (`integer?`) Only for the given namespace, or `nil` for
-                     all.
-      • {enable}     (`boolean?`) true/nil to enable, false to disable
+      • {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.
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 8609d84506..d320db4e51 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -421,7 +421,8 @@ 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()| accepts an `enabled` boolean parameter.
+• |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()|