feat: add "jump" options to vim.diagnostic.config() (#29067)

Problem: There is no easy way to configure the behavior of the default
diagnostic "jump" mappings. For example, some users way want to show the
floating window, and some may not (likewise, some way want to only move
between warnings/errors, or disable the "wrap" parameter).

Solution: Add a "jump" table to vim.diagnostic.config() that sets
default values for vim.diagnostic.jump().

Alternatives: Users can override the default mappings to use the exact
options to vim.diagnostic.jump() that they want, but this has a couple
issues:

  - While the default mappings are not complicated, they are also not
    trivial, so overriding them requires users to understand
    implementation details (specifically things like setting "count"
    properly).
  - If plugins want to change the default mappings, or configure the
    behavior in any way (e.g. floating window display), it becomes even
    harder for users to tweak specific behavior.

vim.diagnostic.config() already works quite well as the "entry point"
for tuning knobs with diagnostic UI elements, so this fits in nicely and
composes well with existing mental models and idioms.

1 files changed, 16 insertions, 2 deletions

diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index be9e54d6cd..2438c48154 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -381,7 +381,8 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
 *vim.diagnostic.JumpOpts*
     Extends: |vim.diagnostic.GetOpts|
 
-    Configuration table with the following keys:
+    Configuration table with the keys listed below. Some parameters can have
+    their default values changed with |vim.diagnostic.config()|.
 
     Fields: ~
       • {diagnostic}?  (`vim.Diagnostic`) The diagnostic to jump to. Mutually
@@ -419,7 +420,7 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
       • {disabled}?  (`boolean`)
 
 *vim.diagnostic.Opts*
-    Each of the configuration options below accepts one of the following:
+    Many of the configuration options below accept one of the following:
     • `false`: Disable this feature
     • `true`: Enable this feature, use default settings.
     • `table`: Enable this feature with overrides. Use an empty table to use
@@ -450,6 +451,9 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
                              displayed before lower severities (e.g. ERROR is
                              displayed before WARN). Options:
                              • {reverse}? (boolean) Reverse sort order
+      • {jump}?              (`vim.diagnostic.Opts.Jump`) Default values for
+                             |vim.diagnostic.jump()|. See
+                             |vim.diagnostic.Opts.Jump|.
 
 *vim.diagnostic.Opts.Float*
 
@@ -509,6 +513,16 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
       • {focus_id}?       (`string`)
       • {border}?         (`string`) see |nvim_open_win()|.
 
+*vim.diagnostic.Opts.Jump*
+
+    Fields: ~
+      • {float}?     (`boolean|vim.diagnostic.Opts.Float`) Default value of
+                     the {float} parameter of |vim.diagnostic.jump()|.
+      • {wrap}?      (`boolean`) Default value of the {wrap} parameter of
+                     |vim.diagnostic.jump()|.
+      • {severity}?  (`vim.diagnostic.SeverityFilter`) Default value of the
+                     {severity} parameter of |vim.diagnostic.jump()|.
+
 *vim.diagnostic.Opts.Signs*
 
     Fields: ~