refactor(diagnostic): remove bufnr parameter from open_float (#16579)

The overwhelming majority of use cases for `open_float` are to view
diagnostics from the current buffer in a floating window. Thus, most use
cases will just `0` or `nil` as the first argument, which makes the
argument effectively useless and wasteful.

In the cause of optimizing for the primary use case, make the `bufnr`
parameter an optional parameter in the options table. This still allows
using an alternative buffer for those that wish to do so, but makes the
"primary" use case much easier.

The old signature is preserved for backward compatibility, though it can
likely be fully deprecated at some point.

runtime/doc/diagnostic.txt

@@ -574,21 +574,24 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
                     diagnostic |diagnostic-structure| or `nil` if {pat} fails
                     to match {str}.
 
-open_float({bufnr}, {opts})                      *vim.diagnostic.open_float()*
+open_float({opts}, {...})                        *vim.diagnostic.open_float()*
                 Show diagnostics in a floating window.
 
                 Parameters: ~
-                    {bufnr}  number|nil Buffer number. Defaults to the current
-                             buffer.
                     {opts}  table|nil Configuration table with the same keys
                             as |vim.lsp.util.open_floating_preview()| in
                             addition to the following:
+                            • bufnr: (number) Buffer number to show
+                              diagnostics from. Defaults to the current
+                              buffer.
                             • namespace: (number) Limit diagnostics to the
                               given namespace
-                             • scope: (string, default "line") Show
-                               diagnostics from the whole buffer ("buffer"),
-                               the current cursor line ("line"), or the
-                               current cursor position ("cursor").
+                            • scope: (string, default "line") Show diagnostics
+                              from the whole buffer ("buffer"), the current
+                              cursor line ("line"), or the current cursor
+                              position ("cursor"). Shorthand versions are also
+                              accepted ("c" for "cursor", "l" for "line", "b"
+                              for "buffer").
                             • pos: (number or table) If {scope} is "line" or
                               "cursor", use this position rather than the
                               cursor position. If a number, interpreted as a
@@ -612,8 +615,8 @@ open_float({bufnr}, {opts})                      *vim.diagnostic.open_float()*
                               return value is the text used to display the
                               diagnostic. Overrides the setting from
                               |vim.diagnostic.config()|.
-                             • prefix: (function, string, or table) Prefix
-                               each diagnostic in the floating window. If a
+                            • prefix: (function, string, or table) Prefix each
+                              diagnostic in the floating window. If a
                               function, it must have the signature
                               (diagnostic, i, total) -> (string, string),
                               where {i} is the index of the diagnostic being
@@ -621,13 +624,13 @@ open_float({bufnr}, {opts})                      *vim.diagnostic.open_float()*
                               diagnostics displayed in the window. The
                               function should return a string which is
                               prepended to each diagnostic in the window as
-                               well as an (optional) highlight group which
-                               will be used to highlight the prefix. If
-                               {prefix} is a table, it is interpreted as a
-                               [text, hl_group] tuple as in |nvim_echo()|;
-                               otherwise, if {prefix} is a string, it is
-                               prepended to each diagnostic in the window with
-                               no highlight. Overrides the setting from
+                              well as an (optional) highlight group which will
+                              be used to highlight the prefix. If {prefix} is
+                              a table, it is interpreted as a [text, hl_group]
+                              tuple as in |nvim_echo()|; otherwise, if
+                              {prefix} is a string, it is prepended to each
+                              diagnostic in the window with no highlight.
+                              Overrides the setting from
                               |vim.diagnostic.config()|.
 
                 Return: ~

runtime/lua/vim/diagnostic.lua

@@ -520,8 +520,8 @@ local function diagnostic_move_pos(opts, pos)
     local float_opts = type(float) == "table" and float or {}
     vim.schedule(function()
       M.open_float(
-        vim.api.nvim_win_get_buf(win_id),
         vim.tbl_extend("keep", float_opts, {
+          bufnr = vim.api.nvim_win_get_buf(win_id),
           scope = "cursor",
           focus = false,
         })
@@ -1135,12 +1135,15 @@ end
 
 --- Show diagnostics in a floating window.
 ---
----@param bufnr number|nil Buffer number. Defaults to the current buffer.
 ---@param opts table|nil Configuration table with the same keys as
 ---            |vim.lsp.util.open_floating_preview()| in addition to the following:
+---            - bufnr: (number) Buffer number to show diagnostics from.
+---                     Defaults to the current buffer.
 ---            - namespace: (number) Limit diagnostics to the given namespace
 ---            - scope: (string, default "line") Show diagnostics from the whole buffer ("buffer"),
 ---                     the current cursor line ("line"), or the current cursor position ("cursor").
+---                     Shorthand versions are also accepted ("c" for "cursor", "l" for "line", "b"
+---                     for "buffer").
 ---            - pos: (number or table) If {scope} is "line" or "cursor", use this position rather
 ---                   than the cursor position. If a number, interpreted as a line number;
 ---                   otherwise, a (row, col) tuple.
@@ -1169,15 +1172,21 @@ end
 ---                      highlight.
 ---                      Overrides the setting from |vim.diagnostic.config()|.
 ---@return tuple ({float_bufnr}, {win_id})
-function M.open_float(bufnr, opts)
+function M.open_float(opts, ...)
+  -- Support old (bufnr, opts) signature
+  local bufnr
+  if opts == nil or type(opts) == "number" then
+    bufnr = opts
+    opts = ...
+  else
     vim.validate {
-    bufnr = { bufnr, 'n', true },
       opts = { opts, 't', true },
     }
+  end
 
   opts = opts or {}
-  bufnr = get_bufnr(bufnr)
-  local scope = opts.scope or "line"
+  bufnr = get_bufnr(bufnr or opts.bufnr)
+  local scope = ({l = "line", c = "cursor", b = "buffer"})[opts.scope] or opts.scope or "line"
   local lnum, col
   if scope == "line" or scope == "cursor" then
     if not opts.pos then

test/functional/lua/diagnostic_spec.lua

@@ -1343,7 +1343,7 @@ describe('vim.diagnostic', function()
         }
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {header = "We're no strangers to love..."})
+        local float_bufnr, winnr = vim.diagnostic.open_float({header = "We're no strangers to love..."})
         local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
         vim.api.nvim_win_close(winnr, true)
         return lines
@@ -1355,7 +1355,7 @@ describe('vim.diagnostic', function()
         }
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {header = {'You know the rules', 'Search'}})
+        local float_bufnr, winnr = vim.diagnostic.open_float({header = {'You know the rules', 'Search'}})
         local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
         vim.api.nvim_win_close(winnr, true)
         return lines
@@ -1370,7 +1370,7 @@ describe('vim.diagnostic', function()
         }
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {header = false, scope="buffer"})
+        local float_bufnr, winnr = vim.diagnostic.open_float({header = false, scope="buffer"})
         local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
         vim.api.nvim_win_close(winnr, true)
         return lines
@@ -1387,7 +1387,7 @@ describe('vim.diagnostic', function()
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
         vim.api.nvim_win_set_cursor(0, {2, 1})
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {header=false})
+        local float_bufnr, winnr = vim.diagnostic.open_float({header=false})
         local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
         vim.api.nvim_win_close(winnr, true)
         return lines
@@ -1402,7 +1402,7 @@ describe('vim.diagnostic', function()
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
         vim.api.nvim_win_set_cursor(0, {1, 1})
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {header=false, pos=1})
+        local float_bufnr, winnr = vim.diagnostic.open_float({header=false, pos=1})
         local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
         vim.api.nvim_win_close(winnr, true)
         return lines
@@ -1419,7 +1419,7 @@ describe('vim.diagnostic', function()
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
         vim.api.nvim_win_set_cursor(0, {2, 2})
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {header=false, scope="cursor"})
+        local float_bufnr, winnr = vim.diagnostic.open_float({header=false, scope="cursor"})
         local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
         vim.api.nvim_win_close(winnr, true)
         return lines
@@ -1434,7 +1434,7 @@ describe('vim.diagnostic', function()
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
         vim.api.nvim_win_set_cursor(0, {1, 1})
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {header=false, scope="cursor", pos={1,3}})
+        local float_bufnr, winnr = vim.diagnostic.open_float({header=false, scope="cursor", pos={1,3}})
         local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
         vim.api.nvim_win_close(winnr, true)
         return lines
@@ -1449,7 +1449,7 @@ describe('vim.diagnostic', function()
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
         vim.api.nvim_win_set_cursor(0, {1, 1})
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {header=false, scope="cursor", pos={0,first_line_len}})
+        local float_bufnr, winnr = vim.diagnostic.open_float({header=false, scope="cursor", pos={0,first_line_len}})
         local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
         vim.api.nvim_win_close(winnr, true)
         return lines
@@ -1665,7 +1665,7 @@ describe('vim.diagnostic', function()
         }
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {header = false, scope = "buffer"})
+        local float_bufnr, winnr = vim.diagnostic.open_float({header = false, scope = "buffer"})
         local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
         vim.api.nvim_win_close(winnr, true)
         return lines
@@ -1678,7 +1678,7 @@ describe('vim.diagnostic', function()
         }
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {header = false, scope = "buffer", prefix = ""})
+        local float_bufnr, winnr = vim.diagnostic.open_float({header = false, scope = "buffer", prefix = ""})
         local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
         vim.api.nvim_win_close(winnr, true)
         return lines
@@ -1691,7 +1691,7 @@ describe('vim.diagnostic', function()
         }
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {
+        local float_bufnr, winnr = vim.diagnostic.open_float({
           header = false,
           prefix = function(_, i, total)
             -- Only show a number if there is more than one diagnostic
@@ -1712,7 +1712,7 @@ describe('vim.diagnostic', function()
         }
         vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
         vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
-        local float_bufnr, winnr = vim.diagnostic.open_float(0, {
+        local float_bufnr, winnr = vim.diagnostic.open_float({
           header = false,
           prefix = function(_, i, total)
             -- Only show a number if there is more than one diagnostic
@@ -1728,7 +1728,21 @@ describe('vim.diagnostic', function()
       ]])
 
       eq("Error executing lua: .../diagnostic.lua:0: prefix: expected 'string' or 'table' or 'function', got 42",
-        pcall_err(exec_lua, [[ vim.diagnostic.open_float(0, { prefix = 42 }) ]]))
+        pcall_err(exec_lua, [[ vim.diagnostic.open_float({ prefix = 42 }) ]]))
+    end)
+
+    it('works with the old signature', function()
+      eq({'1. Syntax error'}, exec_lua [[
+        local diagnostics = {
+          make_error("Syntax error", 0, 1, 0, 3),
+        }
+        vim.api.nvim_win_set_buf(0, diagnostic_bufnr)
+        vim.diagnostic.set(diagnostic_ns, diagnostic_bufnr, diagnostics)
+        local float_bufnr, winnr = vim.diagnostic.open_float(0, { header = false })
+        local lines = vim.api.nvim_buf_get_lines(float_bufnr, 0, -1, false)
+        vim.api.nvim_win_close(winnr, true)
+        return lines
+      ]])
     end)
   end)