refactor(diagnostic): make bufnr arguments consistent (#16323)

Make the bufnr argument have similar semantics across API functions;
namely, a nil value means "all buffers" while 0 means "current buffer".
This increases the flexibility of the API by allowing functions such as
enable() and disable() to apply globally or per-namespace, rather than
only on a specific buffer.

3 files changed, 343 insertions, 54 deletions

diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index d53aae510e..dc00d47193 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -414,8 +414,9 @@ disable({bufnr}, {namespace})                       *vim.diagnostic.disable()*
                 Disable diagnostics in the given buffer.
 
                 Parameters: ~
-                    {bufnr}      number|nil Buffer number. Defaults to the
-                                 current buffer.
+                    {bufnr}      number|nil Buffer number, or 0 for current
+                                 buffer. When omitted, disable diagnostics in
+                                 all buffers.
                     {namespace}  number|nil Only disable diagnostics for the
                                  given namespace.
 
@@ -423,8 +424,9 @@ enable({bufnr}, {namespace})                         *vim.diagnostic.enable()*
                 Enable diagnostics in the given buffer.
 
                 Parameters: ~
-                    {bufnr}      number|nil Buffer number. Defaults to the
-                                 current buffer.
+                    {bufnr}      number|nil Buffer number, or 0 for current
+                                 buffer. When omitted, enable diagnostics in
+                                 all buffers.
                     {namespace}  number|nil Only enable diagnostics for the
                                  given namespace.
 
@@ -550,8 +552,9 @@ hide({namespace}, {bufnr})                             *vim.diagnostic.hide()*
                     {namespace}  number|nil Diagnostic namespace. When
                                  omitted, hide diagnostics from all
                                  namespaces.
-                    {bufnr}      number|nil Buffer number. Defaults to the
-                                 current buffer.
+                    {bufnr}      number|nil Buffer number, or 0 for current
+                                 buffer. When omitted, hide diagnostics in all
+                                 buffers.
 
                                                       *vim.diagnostic.match()*
 match({str}, {pat}, {groups}, {severity_map}, {defaults})
@@ -698,15 +701,16 @@ show({namespace}, {bufnr}, {diagnostics}, {opts})
                     {namespace}    number|nil Diagnostic namespace. When
                                    omitted, show diagnostics from all
                                    namespaces.
-                    {bufnr}        number|nil Buffer number. Defaults to the
-                                   current buffer.
+                    {bufnr}        number|nil Buffer number, or 0 for current
+                                   buffer. When omitted, show diagnostics in
+                                   all buffers.
                     {diagnostics}  table|nil The diagnostics to display. When
                                    omitted, use the saved diagnostics for the
                                    given namespace and buffer. This can be
                                    used to display a list of diagnostics
                                    without saving them or to display only a
                                    subset of diagnostics. May not be used when
-                                   {namespace} is nil.
+                                   {namespace} or {bufnr} is nil.
                     {opts}         table|nil Display options. See
                                    |vim.diagnostic.config()|.
 
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index b30a678eeb..67ab45b97b 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -245,6 +245,11 @@ local bufs_waiting_to_update = setmetatable({}, bufnr_and_namespace_cacher_mt)
 
 ---@private
 local function is_disabled(namespace, bufnr)
+  local ns = M.get_namespace(namespace)
+  if ns.disabled then
+    return true
+  end
+
   if type(diagnostic_disabled[bufnr]) == "table" then
     return diagnostic_disabled[bufnr][namespace]
   end
@@ -1039,19 +1044,22 @@ end
 ---
 ---@param namespace number|nil Diagnostic namespace. When omitted, hide
 ---                            diagnostics from all namespaces.
----@param bufnr number|nil Buffer number. Defaults to the current buffer.
+---@param bufnr number|nil Buffer number, or 0 for current buffer. When
+---                        omitted, hide diagnostics in all buffers.
 function M.hide(namespace, bufnr)
   vim.validate {
     namespace = { namespace, 'n', true },
     bufnr = { bufnr, 'n', true },
   }
 
-  bufnr = get_bufnr(bufnr)
-  local namespaces = namespace and {namespace} or vim.tbl_keys(diagnostic_cache[bufnr])
-  for _, iter_namespace in ipairs(namespaces) do
-    for _, handler in pairs(M.handlers) do
-      if handler.hide then
-        handler.hide(iter_namespace, bufnr)
+  local buffers = bufnr and {get_bufnr(bufnr)} or vim.tbl_keys(diagnostic_cache)
+  for _, iter_bufnr in ipairs(buffers) do
+    local namespaces = namespace and {namespace} or vim.tbl_keys(diagnostic_cache[iter_bufnr])
+    for _, iter_namespace in ipairs(namespaces) do
+      for _, handler in pairs(M.handlers) do
+        if handler.hide then
+          handler.hide(iter_namespace, iter_bufnr)
+        end
       end
     end
   end
@@ -1061,12 +1069,14 @@ end
 ---
 ---@param namespace number|nil Diagnostic namespace. When omitted, show
 ---                            diagnostics from all namespaces.
----@param bufnr number|nil Buffer number. Defaults to the current buffer.
+---@param bufnr number|nil Buffer number, or 0 for current buffer. When omitted, show
+---                        diagnostics in all buffers.
 ---@param diagnostics table|nil The diagnostics to display. When omitted, use the
 ---                             saved diagnostics for the given namespace and
 ---                             buffer. This can be used to display a list of diagnostics
 ---                             without saving them or to display only a subset of
----                             diagnostics. May not be used when {namespace} is nil.
+---                             diagnostics. May not be used when {namespace}
+---                             or {bufnr} is nil.
 ---@param opts table|nil Display options. See |vim.diagnostic.config()|.
 function M.show(namespace, bufnr, diagnostics, opts)
   vim.validate {
@@ -1076,11 +1086,18 @@ function M.show(namespace, bufnr, diagnostics, opts)
     opts = { opts, 't', true },
   }
 
-  bufnr = get_bufnr(bufnr)
-  if not namespace then
-    assert(not diagnostics, "Cannot show diagnostics without a namespace")
-    for iter_namespace in pairs(diagnostic_cache[bufnr]) do
-      M.show(iter_namespace, bufnr, nil, opts)
+  if not bufnr or not namespace then
+    assert(not diagnostics, "Cannot show diagnostics without a buffer and namespace")
+    if not bufnr then
+      for iter_bufnr in pairs(diagnostic_cache) do
+        M.show(namespace, iter_bufnr, nil, opts)
+      end
+    else
+      -- namespace is nil
+      bufnr = get_bufnr(bufnr)
+      for iter_namespace in pairs(diagnostic_cache[bufnr]) do
+        M.show(iter_namespace, bufnr, nil, opts)
+      end
     end
     return
   end
@@ -1323,44 +1340,67 @@ end
 
 --- Disable diagnostics in the given buffer.
 ---
----@param bufnr number|nil Buffer number. Defaults to the current buffer.
+---@param bufnr number|nil Buffer number, or 0 for current buffer. When
+---                        omitted, disable diagnostics in all buffers.
 ---@param namespace number|nil Only disable diagnostics for the given namespace.
 function M.disable(bufnr, namespace)
   vim.validate { bufnr = {bufnr, 'n', true}, namespace = {namespace, 'n', true} }
-  bufnr = get_bufnr(bufnr)
-  if namespace == nil then
-    diagnostic_disabled[bufnr] = true
-    for ns in pairs(diagnostic_cache[bufnr]) do
-      M.hide(ns, bufnr)
+  if bufnr == nil then
+    if namespace == nil then
+      -- Disable everything (including as yet non-existing buffers and
+      -- namespaces) by setting diagnostic_disabled to an empty table and set
+      -- its metatable to always return true. This metatable is removed
+      -- in enable()
+      diagnostic_disabled = setmetatable({}, {
+        __index = function() return true end,
+      })
+    else
+      local ns = M.get_namespace(namespace)
+      ns.disabled = true
     end
   else
-    if type(diagnostic_disabled[bufnr]) ~= "table" then
-      diagnostic_disabled[bufnr] = {}
+    bufnr = get_bufnr(bufnr)
+    if namespace == nil then
+      diagnostic_disabled[bufnr] = true
+    else
+      if type(diagnostic_disabled[bufnr]) ~= "table" then
+        diagnostic_disabled[bufnr] = {}
+      end
+      diagnostic_disabled[bufnr][namespace] = true
     end
-    diagnostic_disabled[bufnr][namespace] = true
-    M.hide(namespace, bufnr)
   end
+
+  M.hide(namespace, bufnr)
 end
 
 --- Enable diagnostics in the given buffer.
 ---
----@param bufnr number|nil Buffer number. Defaults to the current buffer.
+---@param bufnr number|nil Buffer number, or 0 for current buffer. When
+---                        omitted, enable diagnostics in all buffers.
 ---@param namespace number|nil Only enable diagnostics for the given namespace.
 function M.enable(bufnr, namespace)
   vim.validate { bufnr = {bufnr, 'n', true}, namespace = {namespace, 'n', true} }
-  bufnr = get_bufnr(bufnr)
-  if namespace == nil then
-    diagnostic_disabled[bufnr] = nil
-    for ns in pairs(diagnostic_cache[bufnr]) do
-      M.show(ns, bufnr)
+  if bufnr == nil then
+    if namespace == nil then
+      -- Enable everything by setting diagnostic_disabled to an empty table
+      diagnostic_disabled = {}
+    else
+      local ns = M.get_namespace(namespace)
+      ns.disabled = false
     end
   else
-    if type(diagnostic_disabled[bufnr]) ~= "table" then
-      return
+    bufnr = get_bufnr(bufnr)
+    if namespace == nil then
+      diagnostic_disabled[bufnr] = nil
+    else
+      if type(diagnostic_disabled[bufnr]) ~= "table" then
+        return
+      end
+      diagnostic_disabled[bufnr][namespace] = nil
     end
-    diagnostic_disabled[bufnr][namespace] = nil
-    M.show(namespace, bufnr)
   end
+
+  M.show(namespace, bufnr)
 end
 
 --- Parse a diagnostic from a string.
diff --git a/test/functional/lua/diagnostic_spec.lua b/test/functional/lua/diagnostic_spec.lua
index ec53916024..0de1f075c5 100644
--- a/test/functional/lua/diagnostic_spec.lua
+++ b/test/functional/lua/diagnostic_spec.lua
@@ -271,6 +271,8 @@ describe('vim.diagnostic', function()
   describe('show() and hide()', function()
     it('works', function()
       local result = exec_lua [[
+        local other_bufnr = vim.api.nvim_create_buf(true, false)
+
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
 
         local result = {}
@@ -284,36 +286,279 @@ describe('vim.diagnostic', function()
         local ns_2_diags = {
           make_warning("Warning 1", 2, 1, 2, 5),
         }
+        local other_buffer_diags = {
+          make_info("This is interesting", 0, 0, 0, 0)
+        }
 
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, ns_1_diags)
         vim.diagnostic.set(other_ns, diagnostic_bufnr, ns_2_diags)
+        vim.diagnostic.set(diagnostic_ns, other_bufnr, other_buffer_diags)
 
-        -- Both
-        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) + count_extmarks(diagnostic_bufnr, other_ns))
+        -- All buffers and namespaces
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
 
         -- Hide one namespace
         vim.diagnostic.hide(diagnostic_ns)
-        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns))
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
 
         -- Show one namespace
         vim.diagnostic.show(diagnostic_ns)
-        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns))
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
 
-        -- Hide all namespaces
+        -- Hide one buffer
+        vim.diagnostic.hide(nil, other_bufnr)
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        -- Hide everything
         vim.diagnostic.hide()
-        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) + count_extmarks(diagnostic_bufnr, other_ns))
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        -- Show one buffer
+        vim.diagnostic.show(nil, diagnostic_bufnr)
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        return result
+      ]]
+
+      eq(4, result[1])
+      eq(1, result[2])
+      eq(4, result[3])
+      eq(3, result[4])
+      eq(0, result[5])
+      eq(3, result[6])
+    end)
+  end)
+
+  describe('enable() and disable()', function()
+    it('works without arguments', function()
+      local result = exec_lua [[
+        vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
+
+        local result = {}
+
+        vim.diagnostic.config({ underline = false, virtual_text = true })
+
+        local ns_1_diags = {
+          make_error("Error 1", 1, 1, 1, 5),
+          make_warning("Warning on Server 1", 2, 1, 2, 5),
+        }
+        local ns_2_diags = {
+          make_warning("Warning 1", 2, 1, 2, 5),
+        }
+
+        vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, ns_1_diags)
+        vim.diagnostic.set(other_ns, diagnostic_bufnr, ns_2_diags)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns))
+
+        vim.diagnostic.disable()
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns))
+
+        -- Create a new buffer
+        local other_bufnr = vim.api.nvim_create_buf(true, false)
+        local other_buffer_diags = {
+          make_info("This is interesting", 0, 0, 0, 0)
+        }
 
-        -- Show all namespaces
-        vim.diagnostic.show()
-        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) + count_extmarks(diagnostic_bufnr, other_ns))
+        vim.diagnostic.set(diagnostic_ns, other_bufnr, other_buffer_diags)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        vim.diagnostic.enable()
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
 
         return result
       ]]
 
       eq(3, result[1])
       eq(0, result[2])
-      eq(2, result[3])
-      eq(0, result[4])
+      eq(0, result[3])
+      eq(4, result[4])
+    end)
+
+    it('works with only a buffer argument', function()
+      local result = exec_lua [[
+        local other_bufnr = vim.api.nvim_create_buf(true, false)
+
+        vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
+
+        local result = {}
+
+        vim.diagnostic.config({ underline = false, virtual_text = true })
+
+        local ns_1_diags = {
+          make_error("Error 1", 1, 1, 1, 5),
+          make_warning("Warning on Server 1", 2, 1, 2, 5),
+        }
+        local ns_2_diags = {
+          make_warning("Warning 1", 2, 1, 2, 5),
+        }
+        local other_buffer_diags = {
+          make_info("This is interesting", 0, 0, 0, 0)
+        }
+
+        vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, ns_1_diags)
+        vim.diagnostic.set(other_ns, diagnostic_bufnr, ns_2_diags)
+        vim.diagnostic.set(diagnostic_ns, other_bufnr, other_buffer_diags)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        vim.diagnostic.disable(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)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        vim.diagnostic.disable(other_bufnr)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        return result
+      ]]
+
+      eq(4, result[1])
+      eq(1, result[2])
+      eq(4, result[3])
+      eq(3, result[4])
+    end)
+
+    it('works with only a namespace argument', function()
+      local result = exec_lua [[
+        vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
+
+        local result = {}
+
+        vim.diagnostic.config({ underline = false, virtual_text = true })
+
+        local ns_1_diags = {
+          make_error("Error 1", 1, 1, 1, 5),
+          make_warning("Warning on Server 1", 2, 1, 2, 5),
+        }
+        local ns_2_diags = {
+          make_warning("Warning 1", 2, 1, 2, 5),
+        }
+
+        vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, ns_1_diags)
+        vim.diagnostic.set(other_ns, diagnostic_bufnr, ns_2_diags)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns))
+
+        vim.diagnostic.disable(nil, diagnostic_ns)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns))
+
+        vim.diagnostic.enable(nil, diagnostic_ns)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns))
+
+        vim.diagnostic.disable(nil, other_ns)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns))
+
+        return result
+      ]]
+
+      eq(3, result[1])
+      eq(1, result[2])
+      eq(3, result[3])
+      eq(2, result[4])
+    end)
+
+    it('works with both a buffer and a namespace argument', function()
+      local result = exec_lua [[
+        local other_bufnr = vim.api.nvim_create_buf(true, false)
+
+        vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
+
+        local result = {}
+
+        vim.diagnostic.config({ underline = false, virtual_text = true })
+
+        local ns_1_diags = {
+          make_error("Error 1", 1, 1, 1, 5),
+          make_warning("Warning on Server 1", 2, 1, 2, 5),
+        }
+        local ns_2_diags = {
+          make_warning("Warning 1", 2, 1, 2, 5),
+        }
+        local other_buffer_diags = {
+          make_info("This is interesting", 0, 0, 0, 0)
+        }
+
+        vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, ns_1_diags)
+        vim.diagnostic.set(other_ns, diagnostic_bufnr, ns_2_diags)
+        vim.diagnostic.set(diagnostic_ns, other_bufnr, other_buffer_diags)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        vim.diagnostic.disable(diagnostic_bufnr, diagnostic_ns)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        vim.diagnostic.disable(diagnostic_bufnr, other_ns)
+
+        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, diagnostic_ns)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        -- Should have no effect
+        vim.diagnostic.disable(other_bufnr, other_ns)
+
+        table.insert(result, count_extmarks(diagnostic_bufnr, diagnostic_ns) +
+                             count_extmarks(diagnostic_bufnr, other_ns) +
+                             count_extmarks(other_bufnr, diagnostic_ns))
+
+        return result
+      ]]
+
+      eq(4, result[1])
+      eq(2, result[2])
+      eq(1, result[3])
+      eq(3, result[4])
       eq(3, result[5])
     end)
   end)