docs(lua): improvements for LSP and Diagnostic

13 files changed, 568 insertions, 507 deletions

diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 29859f7b05..c61c17c9b0 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -367,79 +367,211 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
       • {user_data}?  (`any`) arbitrary data plugins can add
       • {namespace}?  (`integer`)
 
+*vim.diagnostic.GetOpts*
+    A table with the following keys:
+
+    Fields: ~
+      • {namespace}?  (`integer`) Limit diagnostics to the given namespace.
+      • {lnum}?       (`integer`) Limit diagnostics to the given line number.
+      • {severity}?   (`vim.diagnostic.SeverityFilter`) See
+                      |diagnostic-severity|.
+
+*vim.diagnostic.GotoOpts*
+    Extends: |vim.diagnostic.GetOpts|
+
+    Configuration table with the following keys:
+
+    Fields: ~
+      • {cursor_position}?  (`{[1]:integer,[2]:integer}`, default: current cursor position)
+                            Cursor position as a `(row, col)` tuple. See
+                            |nvim_win_get_cursor()|.
+      • {wrap}?             (`boolean`, default: `true`) Whether to loop
+                            around file or not. Similar to 'wrapscan'.
+      • {severity}          (`vim.diagnostic.Severity`) See
+                            |diagnostic-severity|.
+      • {float}?            (`boolean|vim.diagnostic.Opts.Float`, default:
+                            `true`) If `true`, call
+                            |vim.diagnostic.open_float()| after moving. If a
+                            table, pass the table as the {opts} parameter to
+                            |vim.diagnostic.open_float()|. Unless overridden,
+                            the float will show diagnostics at the new cursor
+                            position (as if "cursor" were passed to the
+                            "scope" option).
+      • {win_id}?           (`integer`, default: `0`) Window ID
+
 *vim.diagnostic.NS*
 
     Fields: ~
       • {name}       (`string`)
-      • {opts}       (`vim.diagnostic.Opts`)
+      • {opts}       (`vim.diagnostic.Opts`) See |vim.diagnostic.Opts|.
       • {user_data}  (`table`)
       • {disabled}?  (`boolean`)
 
 *vim.diagnostic.Opts*
+    Each of the configuration options below accepts 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
+      default values.
+    • `function`: Function with signature (namespace, bufnr) that returns any
+      of the above.
 
     Fields: ~
-      • {float}?             (`boolean|vim.diagnostic.Opts.Float`)
-      • {update_in_insert}?  (`boolean`)
-      • {underline}?         (`boolean|vim.diagnostic.Opts.Underline`)
-      • {virtual_text}?      (`boolean|vim.diagnostic.Opts.VirtualText`)
-      • {signs}?             (`boolean|vim.diagnostic.Opts.Signs`)
-      • {severity_sort}?     (`boolean|{reverse?:boolean}`)
+      • {underline}?         (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`)
+                             Use underline for diagnostics.
+      • {virtual_text}?      (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `true`)
+                             Use virtual text for diagnostics. If multiple
+                             diagnostics are set for a namespace, one prefix
+                             per diagnostic + the last diagnostic message are
+                             shown.
+      • {signs}?             (`boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs`, default: `true`)
+                             Use signs for diagnostics |diagnostic-signs|.
+      • {float}?             (`boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float`)
+                             Options for floating windows. See
+                             |vim.diagnostic.Opts.Float|.
+      • {update_in_insert}?  (`boolean`, default: `false) Update diagnostics
+                             in Insert mode (if `false`, diagnostics are
+                             updated on |InsertLeave|)
+      • {severity_sort}?     (`boolean|{reverse?:boolean}`, default: `false)
+                             Sort diagnostics by severity. This affects the
+                             order in which signs and virtual text are
+                             displayed. When true, higher severities are
+                             displayed before lower severities (e.g. ERROR is
+                             displayed before WARN). Options:
+                             • {reverse}? (boolean) Reverse sort order
 
 *vim.diagnostic.Opts.Float*
 
     Fields: ~
-      • {bufnr}?          (`integer`)
-      • {namespace}?      (`integer`)
-      • {scope}?          (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`)
-      • {pos}?            (`integer|{[1]:integer,[2]:integer}`)
-      • {severity_sort}?  (`boolean|{reverse?:boolean}`)
-      • {severity}?       (`vim.diagnostic.SeverityFilter`)
-      • {header}?         (`string|{[1]:string,[2]:any}`)
-      • {source}?         (`boolean|string`)
-      • {format}?         (`fun(diagnostic:vim.Diagnostic): string`)
-      • {prefix}?         (`string|table`)
-      • {suffix}?         (`string|table`)
+      • {bufnr}?          (`integer`, default: current buffer) Buffer number
+                          to show diagnostics from.
+      • {namespace}?      (`integer`) Limit diagnostics to the given namespace
+      • {scope}?          (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`, 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}?            (`integer|{[1]:integer,[2]:integer}`) 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.
+      • {severity_sort}?  (`boolean|{reverse?:boolean}`, default: `false`)
+                          Sort diagnostics by severity. Overrides the setting
+                          from |vim.diagnostic.config()|.
+      • {severity}?       (`vim.diagnostic.SeverityFilter`) See
+                          |diagnostic-severity|. Overrides the setting from
+                          |vim.diagnostic.config()|.
+      • {header}?         (`string|{[1]:string,[2]:any}`) String to use as the
+                          header for the floating window. If a table, it is
+                          interpreted as a `[text, hl_group]` tuple. Overrides
+                          the setting from |vim.diagnostic.config()|.
+      • {source}?         (`boolean|'if_many'`) Include the diagnostic source
+                          in the message. Use "if_many" to only show sources
+                          if there is more than one source of diagnostics in
+                          the buffer. Otherwise, any truthy value means to
+                          always show the diagnostic source. Overrides the
+                          setting from |vim.diagnostic.config()|.
+      • {format}?         (`fun(diagnostic:vim.Diagnostic): string`) A
+                          function that takes a diagnostic as input and
+                          returns a string. The return value is the text used
+                          to display the diagnostic. Overrides the setting
+                          from |vim.diagnostic.config()|.
+      • {prefix}?         (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`)
+                          Prefix each diagnostic in the floating window:
+                          • If a `function`, {i} is the index of the
+                            diagnostic being evaluated and {total} is the
+                            total number of 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 a `table`, it is interpreted as a `[text,
+                            hl_group]` tuple as in |nvim_echo()|
+                          • If a `string`, it is prepended to each diagnostic
+                            in the window with no highlight. Overrides the
+                            setting from |vim.diagnostic.config()|.
+      • {suffix}?         (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`)
+                          Same as {prefix}, but appends the text to the
+                          diagnostic instead of prepending it. Overrides the
+                          setting from |vim.diagnostic.config()|.
       • {focus_id}?       (`string`)
 
 *vim.diagnostic.Opts.Signs*
 
     Fields: ~
-      • {severity}?  (`vim.diagnostic.SeverityFilter`)
-      • {priority}?  (`integer`)
-      • {text}?      (`table<vim.diagnostic.Severity,string>`)
-      • {numhl}?     (`table<vim.diagnostic.Severity,string>`)
-      • {linehl}?    (`table<vim.diagnostic.Severity,string>`)
-      • {texthl}?    (`table<vim.diagnostic.Severity,string>`)
+      • {severity}?  (`vim.diagnostic.SeverityFilter`) Only show virtual text
+                     for diagnostics matching the given severity
+                     |diagnostic-severity|
+      • {priority}?  (`integer`, default: `10`) Base priority to use for
+                     signs. When {severity_sort} is used, the priority of a
+                     sign is adjusted based on its severity. Otherwise, all
+                     signs use the same priority.
+      • {text}?      (`table<vim.diagnostic.Severity,string>`) A table mapping
+                     |diagnostic-severity| to the sign text to display in the
+                     sign column. The default is to use `"E"`, `"W"`, `"I"`,
+                     and `"H"` for errors, warnings, information, and hints,
+                     respectively. Example: >lua
+                         vim.diagnostic.config({
+                           signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } }
+                         })
+<
+      • {numhl}?     (`table<vim.diagnostic.Severity,string>`) A table mapping
+                     |diagnostic-severity| to the highlight group used for the
+                     line number where the sign is placed.
+      • {linehl}?    (`table<vim.diagnostic.Severity,string>`) A table mapping
+                     |diagnostic-severity| to the highlight group used for the
+                     whole line the sign is placed in.
 
 *vim.diagnostic.Opts.Underline*
 
     Fields: ~
-      • {severity}?  (`vim.diagnostic.SeverityFilter`)
+      • {severity}?  (`vim.diagnostic.SeverityFilter`) Only underline
+                     diagnostics matching the given severity
+                     |diagnostic-severity|.
 
 *vim.diagnostic.Opts.VirtualText*
 
     Fields: ~
-      • {severity}?           (`vim.diagnostic.SeverityFilter`)
-      • {source}?             (`boolean|string`)
-      • {prefix}?             (`string|function`)
-      • {suffix}?             (`string|function`)
-      • {spacing}?            (`integer`)
-      • {format}?             (`function`)
-      • {hl_mode}?            (`'replace'|'combine'|'blend'`)
-      • {virt_text}?          (`{[1]:string,[2]:any}[]`)
-      • {virt_text_pos}?      (`'eol'|'overlay'|'right_align'|'inline'`)
-      • {virt_text_win_col}?  (`integer`)
-      • {virt_text_hide}?     (`boolean`)
-
-*vim.diagnostic.OptsResolved*
-
-    Fields: ~
-      • {float}             (`vim.diagnostic.Opts.Float`)
-      • {update_in_insert}  (`boolean`)
-      • {underline}         (`vim.diagnostic.Opts.Underline`)
-      • {virtual_text}      (`vim.diagnostic.Opts.VirtualText`)
-      • {signs}             (`vim.diagnostic.Opts.Signs`)
-      • {severity_sort}     (`{reverse?:boolean}`)
+      • {severity}?           (`vim.diagnostic.SeverityFilter`) Only show
+                              virtual text for diagnostics matching the given
+                              severity |diagnostic-severity|
+      • {source}?             (`boolean|"if_many"`) Include the diagnostic
+                              source in virtual text. Use `'if_many'` to only
+                              show sources if there is more than one
+                              diagnostic source in the buffer. Otherwise, any
+                              truthy value means to always show the diagnostic
+                              source.
+      • {spacing}?            (`integer`) Amount of empty spaces inserted at
+                              the beginning of the virtual text.
+      • {prefix}?             (`string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)`)
+                              Prepend diagnostic message with prefix. If a
+                              `function`, {i} is the index of the diagnostic
+                              being evaluated, and {total} is the total number
+                              of diagnostics for the line. This can be used to
+                              render diagnostic symbols or error codes.
+      • {suffix}?             (`string|(fun(diagnostic:vim.Diagnostic):
+                              string)`) Append diagnostic message with suffix.
+                              This can be used to render an LSP diagnostic
+                              error code.
+      • {format}?             (`fun(diagnostic:vim.Diagnostic): string`) The
+                              return value is the text used to display the
+                              diagnostic. Example: >lua
+                                  function(diagnostic)
+                                    if diagnostic.severity == vim.diagnostic.severity.ERROR then
+                                      return string.format("E: %s", diagnostic.message)
+                                    end
+                                    return diagnostic.message
+                                  end
+<
+      • {hl_mode}?            (`'replace'|'combine'|'blend'`) See
+                              |nvim_buf_set_extmark()|.
+      • {virt_text}?          (`{[1]:string,[2]:any}[]`) See
+                              |nvim_buf_set_extmark()|.
+      • {virt_text_pos}?      (`'eol'|'overlay'|'right_align'|'inline'`) See
+                              |nvim_buf_set_extmark()|.
+      • {virt_text_win_col}?  (`integer`) See |nvim_buf_set_extmark()|.
+      • {virt_text_hide}?     (`boolean`) See |nvim_buf_set_extmark()|.
 
 
 config({opts}, {namespace})                          *vim.diagnostic.config()*
@@ -461,101 +593,16 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
 
     then virtual text will not be enabled for those diagnostics.
 
-    Note: ~
-      • Each of the configuration options below accepts 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 default values.
-        • `function`: Function with signature (namespace, bufnr) that returns
-          any of the above.
-
     Parameters: ~
-      • {opts}       (`table?`) When omitted or "nil", retrieve the current
-                     configuration. Otherwise, a configuration table with the
-                     following keys:
-                     • underline: (default true) Use underline for
-                       diagnostics. Options:
-                       • severity: Only underline diagnostics matching the
-                         given severity |diagnostic-severity|
-                     • virtual_text: (default true) Use virtual text for
-                       diagnostics. If multiple diagnostics are set for a
-                       namespace, one prefix per diagnostic + the last
-                       diagnostic message are shown. In addition to the
-                       options listed below, the "virt_text" options of
-                       |nvim_buf_set_extmark()| may also be used here (e.g.
-                       "virt_text_pos" and "hl_mode"). Options:
-                       • severity: Only show virtual text for diagnostics
-                         matching the given severity |diagnostic-severity|
-                       • source: (boolean or string) Include the diagnostic
-                         source in virtual text. Use "if_many" to only show
-                         sources if there is more than one diagnostic source
-                         in the buffer. Otherwise, any truthy value means to
-                         always show the diagnostic source.
-                       • spacing: (number) Amount of empty spaces inserted at
-                         the beginning of the virtual text.
-                       • prefix: (string or function) prepend diagnostic
-                         message with prefix. If a function, it must have the
-                         signature (diagnostic, i, total) -> string, where
-                         {diagnostic} is of type |diagnostic-structure|, {i}
-                         is the index of the diagnostic being evaluated, and
-                         {total} is the total number of diagnostics for the
-                         line. This can be used to render diagnostic symbols
-                         or error codes.
-                       • suffix: (string or function) Append diagnostic
-                         message with suffix. If a function, it must have the
-                         signature (diagnostic) -> string, where {diagnostic}
-                         is of type |diagnostic-structure|. This can be used
-                         to render an LSP diagnostic error code.
-                       • format: (function) A function that takes a diagnostic
-                         as input and returns a string. The return value is
-                         the text used to display the diagnostic. Example: >lua
-                             function(diagnostic)
-                               if diagnostic.severity == vim.diagnostic.severity.ERROR then
-                                 return string.format("E: %s", diagnostic.message)
-                               end
-                               return diagnostic.message
-                             end
-<
-                     • signs: (default true) Use signs for diagnostics
-                       |diagnostic-signs|. Options:
-                       • severity: Only show signs for diagnostics matching
-                         the given severity |diagnostic-severity|
-                       • priority: (number, default 10) Base priority to use
-                         for signs. When {severity_sort} is used, the priority
-                         of a sign is adjusted based on its severity.
-                         Otherwise, all signs use the same priority.
-                       • text: (table) A table mapping |diagnostic-severity|
-                         to the sign text to display in the sign column. The
-                         default is to use "E", "W", "I", and "H" for errors,
-                         warnings, information, and hints, respectively.
-                         Example: >lua
-                           vim.diagnostic.config({
-                             signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } }
-                           })
-<
-                       • numhl: (table) A table mapping |diagnostic-severity|
-                         to the highlight group used for the line number where
-                         the sign is placed.
-                       • linehl: (table) A table mapping |diagnostic-severity|
-                         to the highlight group used for the whole line the
-                         sign is placed in.
-                     • float: Options for floating windows. See
-                       |vim.diagnostic.open_float()|.
-                     • update_in_insert: (default false) Update diagnostics in
-                       Insert mode (if false, diagnostics are updated on
-                       InsertLeave)
-                     • severity_sort: (default false) Sort diagnostics by
-                       severity. This affects the order in which signs and
-                       virtual text are displayed. When true, higher
-                       severities are displayed before lower severities (e.g.
-                       ERROR is displayed before WARN). Options:
-                       • reverse: (boolean) Reverse sort order
+      • {opts}       (`vim.diagnostic.Opts?`) When omitted or `nil`, retrieve
+                     the current configuration. Otherwise, a configuration
+                     table (see |vim.diagnostic.Opts|).
       • {namespace}  (`integer?`) Update the options for the given namespace.
                      When omitted, update the global diagnostic options.
 
     Return: ~
-        (`table?`) table of current diagnostic config if `opts` is omitted.
+        (`vim.diagnostic.Opts?`) Current diagnostic config if {opts} is
+        omitted. See |vim.diagnostic.Opts|.
 
 count({bufnr}, {opts})                                *vim.diagnostic.count()*
     Get current diagnostics count.
@@ -563,14 +610,10 @@ count({bufnr}, {opts})                                *vim.diagnostic.count()*
     Parameters: ~
       • {bufnr}  (`integer?`) Buffer number to get diagnostics from. Use 0 for
                  current buffer or nil for all buffers.
-      • {opts}   (`table?`) A table with the following keys:
-                 • namespace: (number) Limit diagnostics to the given
-                   namespace.
-                 • lnum: (number) Limit diagnostics to the given line number.
-                 • severity: See |diagnostic-severity|.
+      • {opts}   (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|.
 
     Return: ~
-        (`table`) A table with actually present severity values as keys (see
+        (`table`) Table with actually present severity values as keys (see
         |diagnostic-severity|) and integer counts as values.
 
 disable({bufnr}, {namespace})                       *vim.diagnostic.disable()*
@@ -599,8 +642,7 @@ fromqflist({list})                               *vim.diagnostic.fromqflist()*
                 |getloclist()|.
 
     Return: ~
-        (`vim.Diagnostic[]`) array of |diagnostic-structure|. See
-        |vim.Diagnostic|.
+        (`vim.Diagnostic[]`) See |vim.Diagnostic|.
 
 get({bufnr}, {opts})                                    *vim.diagnostic.get()*
     Get current diagnostics.
@@ -611,15 +653,10 @@ get({bufnr}, {opts})                                    *vim.diagnostic.get()*
     Parameters: ~
       • {bufnr}  (`integer?`) Buffer number to get diagnostics from. Use 0 for
                  current buffer or nil for all buffers.
-      • {opts}   (`table?`) A table with the following keys:
-                 • namespace: (number) Limit diagnostics to the given
-                   namespace.
-                 • lnum: (number) Limit diagnostics to the given line number.
-                 • severity: See |diagnostic-severity|.
+      • {opts}   (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|.
 
     Return: ~
-        (`vim.Diagnostic[]`) table A list of diagnostic items
-        |diagnostic-structure|. Keys `bufnr`, `end_lnum`, `end_col`, and
+        (`vim.Diagnostic[]`) Fields `bufnr`, `end_lnum`, `end_col`, and
         `severity` are guaranteed to be present. See |vim.Diagnostic|.
 
 get_namespace({namespace})                    *vim.diagnostic.get_namespace()*
@@ -629,20 +666,20 @@ get_namespace({namespace})                    *vim.diagnostic.get_namespace()*
       • {namespace}  (`integer`) Diagnostic namespace
 
     Return: ~
-        (`table`) Namespace metadata
+        (`vim.diagnostic.NS`) Namespace metadata. See |vim.diagnostic.NS|.
 
 get_namespaces()                             *vim.diagnostic.get_namespaces()*
     Get current diagnostic namespaces.
 
     Return: ~
-        (`table<integer,vim.diagnostic.NS>`) A list of active diagnostic
+        (`table<integer,vim.diagnostic.NS>`) List of active diagnostic
         namespaces |vim.diagnostic|.
 
 get_next({opts})                                   *vim.diagnostic.get_next()*
     Get the next diagnostic closest to the cursor position.
 
     Parameters: ~
-      • {opts}  (`table?`) See |vim.diagnostic.goto_next()|
+      • {opts}  (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
 
     Return: ~
         (`vim.Diagnostic?`) Next diagnostic. See |vim.Diagnostic|.
@@ -651,17 +688,17 @@ get_next_pos({opts})                           *vim.diagnostic.get_next_pos()*
     Return the position of the next diagnostic in the current buffer.
 
     Parameters: ~
-      • {opts}  (`table?`) See |vim.diagnostic.goto_next()|
+      • {opts}  (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
 
     Return: ~
-        (`table|false`) Next diagnostic position as a (row, col) tuple or
+        (`table|false`) Next diagnostic position as a `(row, col)` tuple or
         false if no next diagnostic.
 
 get_prev({opts})                                   *vim.diagnostic.get_prev()*
     Get the previous diagnostic closest to the cursor position.
 
     Parameters: ~
-      • {opts}  (`table?`) See |vim.diagnostic.goto_next()|
+      • {opts}  (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
 
     Return: ~
         (`vim.Diagnostic?`) Previous diagnostic. See |vim.Diagnostic|.
@@ -670,39 +707,23 @@ get_prev_pos({opts})                           *vim.diagnostic.get_prev_pos()*
     Return the position of the previous diagnostic in the current buffer.
 
     Parameters: ~
-      • {opts}  (`table?`) See |vim.diagnostic.goto_next()|
+      • {opts}  (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
 
     Return: ~
-        (`table|false`) Previous diagnostic position as a (row, col) tuple or
-        false if there is no prior diagnostic
+        (`table|false`) Previous diagnostic position as a `(row, col)` tuple
+        or `false` if there is no prior diagnostic.
 
 goto_next({opts})                                 *vim.diagnostic.goto_next()*
     Move to the next diagnostic.
 
     Parameters: ~
-      • {opts}  (`table?`) Configuration table with the following keys:
-                • {namespace} (`integer`) Only consider diagnostics from the
-                  given namespace.
-                • {cursor_position}? (`{[1]:integer,[2]:integer}`) Cursor
-                  position as a (row, col) tuple. See |nvim_win_get_cursor()|.
-                  Defaults to the current cursor position.
-                • {wrap}? (`boolean`, default: `true`) Whether to loop around
-                  file or not. Similar to 'wrapscan'.
-                • {severity} (`vim.diagnostic.Severity`) See
-                  |diagnostic-severity|.
-                • {float}? (`boolean|vim.diagnostic.Opts.Float`, default:
-                  `true`) If "true", call |vim.diagnostic.open_float()| after
-                  moving. If a table, pass the table as the {opts} parameter
-                  to |vim.diagnostic.open_float()|. Unless overridden, the
-                  float will show diagnostics at the new cursor position (as
-                  if "cursor" were passed to the "scope" option).
-                • {win_id}? (`integer`, default: `0`) Window ID
+      • {opts}  (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
 
 goto_prev({opts})                                 *vim.diagnostic.goto_prev()*
     Move to the previous diagnostic in the current buffer.
 
     Parameters: ~
-      • {opts}  (`table?`) See |vim.diagnostic.goto_next()|
+      • {opts}  (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|.
 
 hide({namespace}, {bufnr})                             *vim.diagnostic.hide()*
     Hide currently displayed diagnostics.
@@ -740,7 +761,7 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
         WARNING filename:27:3: Variable 'foo' does not exist
 <
 
-    This can be parsed into a diagnostic |diagnostic-structure| with: >lua
+    This can be parsed into |vim.Diagnostic| structure with: >lua
         local s = "WARNING filename:27:3: Variable 'foo' does not exist"
         local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
         local groups = { "severity", "lnum", "col", "message" }
@@ -750,9 +771,8 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
     Parameters: ~
       • {str}           (`string`) String to parse diagnostics from.
       • {pat}           (`string`) Lua pattern with capture groups.
-      • {groups}        (`string[]`) List of fields in a
-                        |diagnostic-structure| to associate with captures from
-                        {pat}.
+      • {groups}        (`string[]`) List of fields in a |vim.Diagnostic|
+                        structure to associate with captures from {pat}.
       • {severity_map}  (`table`) A table mapping the severity field from
                         {groups} with an item from |vim.diagnostic.severity|.
       • {defaults}      (`table?`) Table of default values for any fields not
@@ -760,61 +780,15 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
                         default to 0 and "severity" defaults to ERROR.
 
     Return: ~
-        (`vim.Diagnostic?`) |diagnostic-structure| or `nil` if {pat} fails to
-        match {str}. See |vim.Diagnostic|.
+        (`vim.Diagnostic?`) |vim.Diagnostic| structure or `nil` if {pat} fails
+        to match {str}.
 
 open_float({opts})                               *vim.diagnostic.open_float()*
     Show diagnostics in a floating window.
 
     Parameters: ~
-      • {opts}  (`table?`) 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.
-                • severity_sort: (default false) Sort diagnostics by severity.
-                  Overrides the setting from |vim.diagnostic.config()|.
-                • severity: See |diagnostic-severity|. Overrides the setting
-                  from |vim.diagnostic.config()|.
-                • header: (string or table) String to use as the header for
-                  the floating window. If a table, it is interpreted as a
-                  [text, hl_group] tuple. Overrides the setting from
-                  |vim.diagnostic.config()|.
-                • source: (boolean or string) Include the diagnostic source in
-                  the message. Use "if_many" to only show sources if there is
-                  more than one source of diagnostics in the buffer.
-                  Otherwise, any truthy value means to always show the
-                  diagnostic source. Overrides the setting from
-                  |vim.diagnostic.config()|.
-                • format: (function) A function that takes a diagnostic as
-                  input and returns a string. The 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 function, it must have the
-                  signature (diagnostic, i, total) -> (string, string), where
-                  {i} is the index of the diagnostic being evaluated and
-                  {total} is the total number of 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
-                  |vim.diagnostic.config()|.
-                • suffix: Same as {prefix}, but appends the text to the
-                  diagnostic instead of prepending it. Overrides the setting
-                  from |vim.diagnostic.config()|.
+      • {opts}  (`vim.diagnostic.Opts.Float?`) See
+                |vim.diagnostic.Opts.Float|.
 
     Return (multiple): ~
         (`integer?`) float_bufnr
@@ -840,10 +814,9 @@ set({namespace}, {bufnr}, {diagnostics}, {opts})        *vim.diagnostic.set()*
     Parameters: ~
       • {namespace}    (`integer`) The diagnostic namespace
       • {bufnr}        (`integer`) Buffer number
-      • {diagnostics}  (`vim.Diagnostic[]`) A list of diagnostic items
-                       |diagnostic-structure|. See |vim.Diagnostic|.
-      • {opts}         (`table?`) Display options to pass to
-                       |vim.diagnostic.show()|
+      • {diagnostics}  (`vim.Diagnostic[]`) See |vim.Diagnostic|.
+      • {opts}         (`vim.diagnostic.Opts?`) Display options to pass to
+                       |vim.diagnostic.show()|. See |vim.diagnostic.Opts|.
 
 setloclist({opts})                               *vim.diagnostic.setloclist()*
     Add buffer diagnostics to the location list.
@@ -890,19 +863,18 @@ show({namespace}, {bufnr}, {diagnostics}, {opts})
                        list of diagnostics without saving them or to display
                        only a subset of diagnostics. May not be used when
                        {namespace} or {bufnr} is nil. See |vim.Diagnostic|.
-      • {opts}         (`table?`) Display options. See
-                       |vim.diagnostic.config()|.
+      • {opts}         (`vim.diagnostic.Opts?`) Display options. See
+                       |vim.diagnostic.Opts|.
 
 toqflist({diagnostics})                            *vim.diagnostic.toqflist()*
     Convert a list of diagnostics to a list of quickfix items that can be
     passed to |setqflist()| or |setloclist()|.
 
     Parameters: ~
-      • {diagnostics}  (`vim.Diagnostic[]`) List of diagnostics
-                       |diagnostic-structure|. See |vim.Diagnostic|.
+      • {diagnostics}  (`vim.Diagnostic[]`) See |vim.Diagnostic|.
 
     Return: ~
-        (`table[]`) of quickfix list items |setqflist-what|
+        (`table[]`) Quickfix list items |setqflist-what|
 
 
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 511fb590cc..31b1c412c7 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -673,17 +673,18 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
 
     Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the
     result. Parameters are the same as |vim.lsp.buf_request_all()| but the
-    result is different. Waits a maximum of {timeout_ms} (default 1000) ms.
+    result is different. Waits a maximum of {timeout_ms}.
 
     Parameters: ~
       • {bufnr}       (`integer`) Buffer handle, or 0 for current.
       • {method}      (`string`) LSP method name
       • {params}      (`table?`) Parameters to send to the server
-      • {timeout_ms}  (`integer?`) Maximum time in milliseconds to wait for a
-                      result. Defaults to 1000
+      • {timeout_ms}  (`integer?`, default: `1000`) Maximum time in
+                      milliseconds to wait for a result.
 
     Return (multiple): ~
-        (`table`) result Map of client_id:request_result.
+        (`table<integer, {err: lsp.ResponseError, result: any}>?`) result Map
+        of client_id:request_result.
         (`string?`) err On timeout, cancel, or error, `err` is a string
         describing the failure reason, and `result` is nil.
 
@@ -946,13 +947,15 @@ Lua module: vim.lsp.client                                        *lsp-client*
                                 server.
       • {config}                (`vim.lsp.ClientConfig`) copy of the table
                                 that was passed by the user to
-                                |vim.lsp.start_client()|.
+                                |vim.lsp.start_client()|. See
+                                |vim.lsp.ClientConfig|.
       • {server_capabilities}   (`lsp.ServerCapabilities?`) Response from the
                                 server sent on initialize` describing the
                                 server's capabilities.
       • {progress}              (`vim.lsp.Client.Progress`) A ring buffer
                                 (|vim.ringbuf()|) containing progress messages
-                                sent by the server.
+                                sent by the server. See
+                                |vim.lsp.Client.Progress|.
       • {initialized}           (`true?`)
       • {workspace_folders}     (`lsp.WorkspaceFolder[]?`) The workspace
                                 folders configured in the client when the
@@ -968,9 +971,28 @@ Lua module: vim.lsp.client                                        *lsp-client*
                                 action, code lenses, ...) triggers the
                                 command. Client commands take precedence over
                                 the global command registry.
-      • {settings}              (`table`)
-      • {flags}                 (`table`)
-      • {get_language_id}       (`fun(bufnr: integer, filetype: string): string`)
+      • {settings}              (`table`) Map with language server specific
+                                settings. These are returned to the language
+                                server if requested via
+                                `workspace/configuration`. Keys are
+                                case-sensitive.
+      • {flags}                 (`table`) A table with flags for the client.
+                                The current (experimental) flags are:
+                                • {allow_incremental_sync}? (`boolean`) Allow
+                                  using incremental sync for buffer edits
+                                  (defailt: `true`)
+                                • {debounce_text_changes} (`integer`, default:
+                                  `150`) Debounce `didChange` notifications to
+                                  the server by the given number in
+                                  milliseconds. No debounce occurs if `nil`.
+                                • {exit_timeout} (`integer|false`, default:
+                                  `false`) Milliseconds to wait for server to
+                                  exit cleanly after sending the "shutdown"
+                                  request before sending kill -15. If set to
+                                  false, nvim exits immediately after sending
+                                  the "shutdown" request to the server.
+      • {get_language_id}       (`fun(bufnr: integer, filetype: string):
+                                string`)
       • {capabilities}          (`lsp.ClientCapabilities`) The capabilities
                                 provided by the client (editor or tool)
       • {dynamic_capabilities}  (`lsp.DynamicCapabilities`)
@@ -1021,6 +1043,7 @@ Lua module: vim.lsp.client                                        *lsp-client*
 *vim.lsp.Client.Progress*
     Extends: |vim.Ringbuf|
 
+
     Fields: ~
       • {pending}  (`table<lsp.ProgressToken,lsp.LSPAny>`)
 
@@ -1070,10 +1093,8 @@ Lua module: vim.lsp.client                                        *lsp-client*
       • {handlers}?           (`table<string,function>`) Map of language
                               server method names to |lsp-handler|
       • {settings}?           (`table`) Map with language server specific
-                              settings. These are returned to the language
-                              server if requested via
-                              `workspace/configuration`. Keys are
-                              case-sensitive.
+                              settings. See the {settings} in
+                              |vim.lsp.Client|.
       • {commands}?           (`table<string,fun(command: lsp.Command, ctx:
                               table)>`) Table that maps string of clientside
                               commands to user-defined functions. Commands
@@ -1101,13 +1122,14 @@ Lua module: vim.lsp.client                                        *lsp-client*
                               possible errors. Use
                               `vim.lsp.rpc.client_errors[code]` to get
                               human-friendly name.
-      • {before_init}?        (`vim.lsp.client.before_init_cb`) Callback
-                              invoked before the LSP "initialize" phase, where
-                              `params` contains the parameters being sent to
-                              the server and `config` is the config that was
-                              passed to |vim.lsp.start_client()|. You can use
-                              this to modify parameters before they are sent.
-      • {on_init}?            (`elem_or_list<vim.lsp.client.on_init_cb>`)
+      • {before_init}?        (`fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)`)
+                              Callback invoked before the LSP "initialize"
+                              phase, where `params` contains the parameters
+                              being sent to the server and `config` is the
+                              config that was passed to
+                              |vim.lsp.start_client()|. You can use this to
+                              modify parameters before they are sent.
+      • {on_init}?            (`elem_or_list<fun(client: vim.lsp.Client, initialize_result: lsp.InitializeResult)>`)
                               Callback invoked after LSP "initialize", where
                               `result` is a table of `capabilities` and
                               anything else the server may send. For example,
@@ -1115,13 +1137,13 @@ Lua module: vim.lsp.client                                        *lsp-client*
                               if `capabilities.offsetEncoding` was sent to it.
                               You can only modify the `client.offset_encoding`
                               here before any notifications are sent.
-      • {on_exit}?            (`elem_or_list<vim.lsp.client.on_exit_cb>`)
+      • {on_exit}?            (`elem_or_list<fun(code: integer, signal: integer, client_id: integer)>`)
                               Callback invoked on client exit.
                               • code: exit code of the process
                               • signal: number describing the signal used to
                                 terminate (if any)
                               • client_id: client handle
-      • {on_attach}?          (`elem_or_list<vim.lsp.client.on_attach_cb>`)
+      • {on_attach}?          (`elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>`)
                               Callback invoked when client attaches to a
                               buffer.
       • {trace}?              (`'off'|'messages'|'verbose'`, default: "off")
@@ -1129,18 +1151,19 @@ Lua module: vim.lsp.client                                        *lsp-client*
                               initialize request. Invalid/empty values will
       • {flags}?              (`table`) A table with flags for the client. The
                               current (experimental) flags are:
-                              • allow_incremental_sync (bool, default true):
-                                Allow using incremental sync for buffer edits
-                              • debounce_text_changes (number, default 150):
-                                Debounce didChange notifications to the server
-                                by the given number in milliseconds. No
-                                debounce occurs if nil
-                              • exit_timeout (number|boolean, default false):
-                                Milliseconds to wait for server to exit
-                                cleanly after sending the "shutdown" request
-                                before sending kill -15. If set to false, nvim
-                                exits immediately after sending the "shutdown"
-                                request to the server.
+                              • {allow_incremental_sync}? (`boolean`) Allow
+                                using incremental sync for buffer edits
+                                (defailt: `true`)
+                              • {debounce_text_changes} (`integer`, default:
+                                `150`) Debounce `didChange` notifications to
+                                the server by the given number in
+                                milliseconds. No debounce occurs if `nil`.
+                              • {exit_timeout} (`integer|false`, default:
+                                `false`) Milliseconds to wait for server to
+                                exit cleanly after sending the "shutdown"
+                                request before sending kill -15. If set to
+                                false, nvim exits immediately after sending
+                                the "shutdown" request to the server.
       • {root_dir}?           (`string`) Directory where the LSP server will
                               base its workspaceFolders, rootUri, and rootPath
                               on initialization.
@@ -1176,6 +1199,7 @@ Lua module: vim.lsp.buf                                              *lsp-buf*
 *vim.lsp.LocationOpts*
     Extends: |vim.lsp.ListOpts|
 
+
     Fields: ~
       • {reuse_win}?  (`boolean`) Jump to existing window if buffer is already
                       open.
@@ -1443,7 +1467,7 @@ on_diagnostic({_}, {result}, {ctx}, {config})
     Parameters: ~
       • {result}  (`lsp.DocumentDiagnosticReport`)
       • {ctx}     (`lsp.HandlerContext`)
-      • {config}  (`table`) Configuration table (see
+      • {config}  (`vim.diagnostic.Opts`) Configuration table (see
                   |vim.diagnostic.config()|).
 
                                  *vim.lsp.diagnostic.on_publish_diagnostics()*
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index c785106ca8..42577cae2e 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1831,15 +1831,15 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter})           *vim.inspect_pos()*
       • {col}     (`integer?`) col to inspect, 0-based. Defaults to the col of
                   the current cursor
       • {filter}  (`table?`) Table with key-value pairs to filter the items
-                  • {syntax} (`boolean`) Include syntax based highlight groups
-                    (defaults to true)
-                  • {treesitter} (`boolean`) Include treesitter based
-                    highlight groups (defaults to true)
+                  • {syntax} (`boolean`, default: `true`) Include syntax based
+                    highlight groups.
+                  • {treesitter} (`boolean`, default: `true`) Include
+                    treesitter based highlight groups.
                   • {extmarks} (`boolean|"all"`, default: true) Include
                     extmarks. When `all`, then extmarks without a `hl_group`
                     will also be included.
-                  • {semantic_tokens} (`boolean`) Include semantic token
-                    highlights (defaults to true)
+                  • {semantic_tokens} (`boolean`, default: true) Include
+                    semantic token highlights.
 
     Return: ~
         (`table`) a table with the following key-value pairs. Items are in
@@ -1863,7 +1863,16 @@ vim.show_pos({bufnr}, {row}, {col}, {filter})                 *vim.show_pos()*
                   the current cursor
       • {col}     (`integer?`) col to inspect, 0-based. Defaults to the col of
                   the current cursor
-      • {filter}  (`table?`) see |vim.inspect_pos()|
+      • {filter}  (`table?`) A table with the following fields:
+                  • {syntax} (`boolean`, default: `true`) Include syntax based
+                    highlight groups.
+                  • {treesitter} (`boolean`, default: `true`) Include
+                    treesitter based highlight groups.
+                  • {extmarks} (`boolean|"all"`, default: true) Include
+                    extmarks. When `all`, then extmarks without a `hl_group`
+                    will also be included.
+                  • {semantic_tokens} (`boolean`, default: true) Include
+                    semantic token highlights.
 
 
 
@@ -1989,7 +1998,7 @@ vim.gsplit({s}, {sep}, {opts})                                  *vim.gsplit()*
                   end of the sequence.
 
     Return: ~
-        (`function`) Iterator over the split components
+        (`fun():string?`) Iterator over the split components
 
     See also: ~
       • |string.gmatch()|
@@ -2089,7 +2098,7 @@ vim.ringbuf({size})                                            *vim.ringbuf()*
       • {size}  (`integer`)
 
     Return: ~
-        (`table`)
+        (`vim.Ringbuf`) ringbuf See |vim.Ringbuf|.
 
 vim.spairs({t})                                                 *vim.spairs()*
     Enumerates key-value pairs of a table, ordered by key.
@@ -2097,8 +2106,10 @@ vim.spairs({t})                                                 *vim.spairs()*
     Parameters: ~
       • {t}  (`table`) Dict-like table
 
-    Return: ~
-        (`function`) |for-in| iterator over sorted keys and their values
+    Return (multiple): ~
+        (`fun(table: table<K, V>, index?: K):K, V`) |for-in| iterator over
+        sorted keys and their values
+        (`table`)
 
     See also: ~
       • Based on
@@ -2334,8 +2345,8 @@ vim.tbl_map({func}, {t})                                       *vim.tbl_map()*
     Apply a function to all values of a table.
 
     Parameters: ~
-      • {func}  (`function`) Function
-      • {t}     (`table`) Table
+      • {func}  (`fun(value: T): any`) Function
+      • {t}     (`table<any, T>`) Table
 
     Return: ~
         (`table`) Table of transformed values
diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua
index a19d40c50d..2999630fce 100644
--- a/runtime/lua/vim/_inspector.lua
+++ b/runtime/lua/vim/_inspector.lua
@@ -1,17 +1,20 @@
 --- @class vim._inspector.Filter
 --- @inlinedoc
 ---
---- Include syntax based highlight groups (defaults to true)
+--- Include syntax based highlight groups.
+--- (default: `true`)
 --- @field syntax boolean
 ---
---- Include treesitter based highlight groups (defaults to true)
+--- Include treesitter based highlight groups.
+--- (default: `true`)
 --- @field treesitter boolean
 ---
 --- Include extmarks. When `all`, then extmarks without a `hl_group` will also be included.
 --- (default: true)
 --- @field extmarks boolean|"all"
 ---
---- Include semantic token highlights (defaults to true)
+--- Include semantic token highlights.
+--- (default: true)
 --- @field semantic_tokens boolean
 local defaults = {
   syntax = true,
@@ -145,7 +148,7 @@ end
 ---@param bufnr? integer defaults to the current buffer
 ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor
 ---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor
----@param filter? vim._inspector.Filter (table) see |vim.inspect_pos()|
+---@param filter? vim._inspector.Filter
 function vim.show_pos(bufnr, row, col, filter)
   local items = vim.inspect_pos(bufnr, row, col, filter)
 
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index 3979e5512c..9483474a40 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -42,15 +42,44 @@ local M = {}
 ---
 --- @field namespace? integer
 
+--- Each of the configuration options below accepts 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 default values.
+--- - `function`: Function with signature (namespace, bufnr) that returns any of the above.
 --- @class vim.diagnostic.Opts
---- @field float? boolean|vim.diagnostic.Opts.Float
+---
+--- Use underline for diagnostics.
+--- (default: `true`)
+--- @field underline? boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline
+---
+--- Use virtual text for diagnostics. If multiple diagnostics are set for a
+--- namespace, one prefix per diagnostic + the last diagnostic message are
+--- shown.
+--- (default: `true`)
+--- @field virtual_text? boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText
+---
+--- Use signs for diagnostics |diagnostic-signs|.
+--- (default: `true`)
+--- @field signs? boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs
+---
+--- Options for floating windows. See |vim.diagnostic.Opts.Float|.
+--- @field float? boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float
+---
+--- Update diagnostics in Insert mode
+--- (if `false`, diagnostics are updated on |InsertLeave|)
+--- (default: `false)
 --- @field update_in_insert? boolean
---- @field underline? boolean|vim.diagnostic.Opts.Underline
---- @field virtual_text? boolean|vim.diagnostic.Opts.VirtualText
---- @field signs? boolean|vim.diagnostic.Opts.Signs
+---
+--- Sort diagnostics by severity. This affects the order in which signs and
+--- virtual text are displayed. When true, higher severities are displayed
+--- before lower severities (e.g. ERROR is displayed before WARN).
+--- Options:
+---   - {reverse}? (boolean) Reverse sort order
+--- (default: `false)
 --- @field severity_sort? boolean|{reverse?:boolean}
 
---- @class vim.diagnostic.OptsResolved
+--- @class (private) vim.diagnostic.OptsResolved
 --- @field float vim.diagnostic.Opts.Float
 --- @field update_in_insert boolean
 --- @field underline vim.diagnostic.Opts.Underline
@@ -59,42 +88,156 @@ local M = {}
 --- @field severity_sort {reverse?:boolean}
 
 --- @class vim.diagnostic.Opts.Float
+---
+--- Buffer number to show diagnostics from.
+--- (default: current buffer)
 --- @field bufnr? integer
+---
+--- Limit diagnostics to the given namespace
 --- @field namespace? integer
+---
+--- 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`).
+--- (default: `line`)
 --- @field scope? 'line'|'buffer'|'cursor'|'c'|'l'|'b'
+---
+--- 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.
 --- @field pos? integer|{[1]:integer,[2]:integer}
+---
+--- Sort diagnostics by severity.
+--- Overrides the setting from |vim.diagnostic.config()|.
+--- (default: `false`)
 --- @field severity_sort? boolean|{reverse?:boolean}
+---
+--- See |diagnostic-severity|.
+--- Overrides the setting from |vim.diagnostic.config()|.
 --- @field severity? vim.diagnostic.SeverityFilter
+---
+--- String to use as the header for the floating window. If a table, it is
+--- interpreted as a `[text, hl_group]` tuple.
+--- Overrides the setting from |vim.diagnostic.config()|.
 --- @field header? string|{[1]:string,[2]:any}
---- @field source? boolean|string
+---
+--- Include the diagnostic source in the message.
+--- Use "if_many" to only show sources if there is more than one source of
+--- diagnostics in the buffer. Otherwise, any truthy value means to always show
+--- the diagnostic source.
+--- Overrides the setting from |vim.diagnostic.config()|.
+--- @field source? boolean|'if_many'
+---
+--- A function that takes a diagnostic as input and returns a string.
+--- The return value is the text used to display the diagnostic.
+--- Overrides the setting from |vim.diagnostic.config()|.
 --- @field format? fun(diagnostic:vim.Diagnostic): string
+---
+--- Prefix each diagnostic in the floating window:
+--- - If a `function`, {i} is the index of the diagnostic being evaluated and
+---   {total} is the total number of 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 a `table`, it is interpreted as a `[text, hl_group]` tuple as
+---   in |nvim_echo()|
+--- - If a `string`, it is prepended to each diagnostic in the window with no
+---   highlight.
+--- Overrides the setting from |vim.diagnostic.config()|.
 --- @field prefix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)
+---
+--- Same as {prefix}, but appends the text to the diagnostic instead of
+--- prepending it.
+--- Overrides the setting from |vim.diagnostic.config()|.
 --- @field suffix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)
+---
 --- @field focus_id? string
 
 --- @class vim.diagnostic.Opts.Underline
+---
+--- Only underline diagnostics matching the given
+--- severity |diagnostic-severity|.
 --- @field severity? vim.diagnostic.SeverityFilter
 
 --- @class vim.diagnostic.Opts.VirtualText
+---
+--- Only show virtual text for diagnostics matching the given
+--- severity |diagnostic-severity|
 --- @field severity? vim.diagnostic.SeverityFilter
---- @field source? boolean|string
---- @field prefix? string|function
---- @field suffix? string|function
+---
+--- Include the diagnostic source in virtual text. Use `'if_many'` to only
+--- show sources if there is more than one diagnostic source in the buffer.
+--- Otherwise, any truthy value means to always show the diagnostic source.
+--- @field source? boolean|"if_many"
+---
+--- Amount of empty spaces inserted at the beginning of the virtual text.
 --- @field spacing? integer
---- @field format? function
+---
+--- Prepend diagnostic message with prefix. If a `function`, {i} is the index
+--- of the diagnostic being evaluated, and {total} is the total number of
+--- diagnostics for the line. This can be used to render diagnostic symbols
+--- or error codes.
+--- @field prefix? string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)
+---
+--- Append diagnostic message with suffix.
+--- This can be used to render an LSP diagnostic error code.
+--- @field suffix? string|(fun(diagnostic:vim.Diagnostic): string)
+---
+--- The return value is the text used to display the diagnostic. Example:
+--- ```lua
+--- function(diagnostic)
+---   if diagnostic.severity == vim.diagnostic.severity.ERROR then
+---     return string.format("E: %s", diagnostic.message)
+---   end
+---   return diagnostic.message
+--- end
+--- ```
+--- @field format? fun(diagnostic:vim.Diagnostic): string
+---
+--- See |nvim_buf_set_extmark()|.
 --- @field hl_mode? 'replace'|'combine'|'blend'
+---
+--- See |nvim_buf_set_extmark()|.
 --- @field virt_text? {[1]:string,[2]:any}[]
+---
+--- See |nvim_buf_set_extmark()|.
 --- @field virt_text_pos? 'eol'|'overlay'|'right_align'|'inline'
+---
+--- See |nvim_buf_set_extmark()|.
 --- @field virt_text_win_col? integer
+---
+--- See |nvim_buf_set_extmark()|.
 --- @field virt_text_hide? boolean
 
 --- @class vim.diagnostic.Opts.Signs
+---
+--- Only show virtual text for diagnostics matching the given
+--- severity |diagnostic-severity|
 --- @field severity? vim.diagnostic.SeverityFilter
+---
+--- Base priority to use for signs. When {severity_sort} is used, the priority
+--- of a sign is adjusted based on its severity.
+--- Otherwise, all signs use the same priority.
+--- (default: `10`)
 --- @field priority? integer
+---
+--- A table mapping |diagnostic-severity| to the sign text to display in the
+--- sign column. The default is to use `"E"`, `"W"`, `"I"`, and `"H"` for errors,
+--- warnings, information, and hints, respectively. Example:
+--- ```lua
+--- vim.diagnostic.config({
+---   signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } }
+--- })
+--- ```
 --- @field text? table<vim.diagnostic.Severity,string>
+---
+--- A table mapping |diagnostic-severity| to the highlight group used for the
+--- line number where the sign is placed.
 --- @field numhl? table<vim.diagnostic.Severity,string>
+---
+--- A table mapping |diagnostic-severity| to the highlight group used for the
+--- whole line the sign is placed in.
 --- @field linehl? table<vim.diagnostic.Severity,string>
---- @field texthl? table<vim.diagnostic.Severity,string>
 
 --- @nodoc
 --- @enum vim.diagnostic.Severity
@@ -752,83 +895,11 @@ end
 ---
 --- then virtual text will not be enabled for those diagnostics.
 ---
----@note Each of the configuration options below accepts 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 default values.
----         - `function`: Function with signature (namespace, bufnr) that returns any of the above.
----
----@param opts vim.diagnostic.Opts? (table?) When omitted or "nil", retrieve the current
----       configuration. Otherwise, a configuration table with the following keys:
----       - underline: (default true) Use underline for diagnostics. Options:
----           * severity: Only underline diagnostics matching the given
----             severity |diagnostic-severity|
----       - virtual_text: (default true) Use virtual text for diagnostics. If multiple diagnostics
----         are set for a namespace, one prefix per diagnostic + the last diagnostic
----         message are shown. In addition to the options listed below, the
----         "virt_text" options of |nvim_buf_set_extmark()| may also be used here
----         (e.g. "virt_text_pos" and "hl_mode").
----         Options:
----         * severity: Only show virtual text for diagnostics matching the given
----         severity |diagnostic-severity|
----         * source: (boolean or string) Include the diagnostic source in virtual
----                   text. Use "if_many" to only show sources if there is more than
----                   one diagnostic source in the buffer. Otherwise, any truthy value
----                   means to always show the diagnostic source.
----         * spacing: (number) Amount of empty spaces inserted at the beginning
----                    of the virtual text.
----         * prefix: (string or function) prepend diagnostic message with prefix.
----                   If a function, it must have the signature (diagnostic, i, total)
----                   -> string, where {diagnostic} is of type |diagnostic-structure|,
----                   {i} is the index of the diagnostic being evaluated, and {total}
----                   is the total number of diagnostics for the line. This can be
----                   used to render diagnostic symbols or error codes.
----         * suffix: (string or function) Append diagnostic message with suffix.
----                   If a function, it must have the signature (diagnostic) ->
----                   string, where {diagnostic} is of type |diagnostic-structure|.
----                   This can be used to render an LSP diagnostic error code.
----         * format: (function) A function that takes a diagnostic as input and
----                   returns a string. The return value is the text used to display
----                   the diagnostic. Example:
----              ```lua
----                  function(diagnostic)
----                    if diagnostic.severity == vim.diagnostic.severity.ERROR then
----                      return string.format("E: %s", diagnostic.message)
----                    end
----                    return diagnostic.message
----                  end
----                  ```
----       - signs: (default true) Use signs for diagnostics |diagnostic-signs|. Options:
----         * severity: Only show signs for diagnostics matching the given
----         severity |diagnostic-severity|
----         * priority: (number, default 10) Base priority to use for signs. When
----         {severity_sort} is used, the priority of a sign is adjusted based on
----         its severity. Otherwise, all signs use the same priority.
----         * text: (table) A table mapping |diagnostic-severity| to the sign text
----         to display in the sign column. The default is to use "E", "W", "I", and "H"
----         for errors, warnings, information, and hints, respectively. Example:
----            ```lua
----                vim.diagnostic.config({
----                  signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } }
----                })
----            ```
----         * numhl: (table) A table mapping |diagnostic-severity| to the highlight
----         group used for the line number where the sign is placed.
----         * linehl: (table) A table mapping |diagnostic-severity| to the highlight group
----         used for the whole line the sign is placed in.
----       - float: Options for floating windows. See |vim.diagnostic.open_float()|.
----       - update_in_insert: (default false) Update diagnostics in Insert mode (if false,
----                           diagnostics are updated on InsertLeave)
----       - severity_sort: (default false) Sort diagnostics by severity. This affects the order in
----         which signs and virtual text are displayed. When true, higher severities
----         are displayed before lower severities (e.g. ERROR is displayed before WARN).
----         Options:
----         * reverse: (boolean) Reverse sort order
----
----@param namespace integer? Update the options for the given namespace. When omitted, update the
----                          global diagnostic options.
----
----@return vim.diagnostic.Opts? (table?) table of current diagnostic config if `opts` is omitted.
+---@param opts vim.diagnostic.Opts? When omitted or `nil`, retrieve the current
+---       configuration. Otherwise, a configuration table (see |vim.diagnostic.Opts|).
+---@param namespace integer? Update the options for the given namespace.
+---                          When omitted, update the global diagnostic options.
+---@return vim.diagnostic.Opts? : Current diagnostic config if {opts} is omitted.
 function M.config(opts, namespace)
   vim.validate({
     opts = { opts, 't', true },
@@ -873,8 +944,8 @@ end
 ---
 ---@param namespace integer The diagnostic namespace
 ---@param bufnr integer Buffer number
----@param diagnostics vim.Diagnostic[] A list of diagnostic items |diagnostic-structure|
----@param opts? vim.diagnostic.Opts (table) Display options to pass to |vim.diagnostic.show()|
+---@param diagnostics vim.Diagnostic[]
+---@param opts? vim.diagnostic.Opts Display options to pass to |vim.diagnostic.show()|
 function M.set(namespace, bufnr, diagnostics, opts)
   vim.validate({
     namespace = { namespace, 'n' },
@@ -908,7 +979,7 @@ end
 --- Get namespace metadata.
 ---
 ---@param namespace integer Diagnostic namespace
----@return vim.diagnostic.NS (table) Namespace metadata
+---@return vim.diagnostic.NS : Namespace metadata
 function M.get_namespace(namespace)
   vim.validate({ namespace = { namespace, 'n' } })
   if not all_namespaces[namespace] then
@@ -933,22 +1004,21 @@ end
 
 --- Get current diagnostic namespaces.
 ---
----@return table<integer,vim.diagnostic.NS> A list of active diagnostic namespaces |vim.diagnostic|.
+---@return table<integer,vim.diagnostic.NS> : List of active diagnostic namespaces |vim.diagnostic|.
 function M.get_namespaces()
   return vim.deepcopy(all_namespaces, true)
 end
 
 --- Get current diagnostics.
 ---
---- Modifying diagnostics in the returned table has no effect. To set diagnostics in a buffer, use |vim.diagnostic.set()|.
+--- Modifying diagnostics in the returned table has no effect.
+--- To set diagnostics in a buffer, use |vim.diagnostic.set()|.
 ---
 ---@param bufnr integer? Buffer number to get diagnostics from. Use 0 for
----                        current buffer or nil for all buffers.
----@param opts? vim.diagnostic.GetOpts (table) A table with the following keys:
----                        - namespace: (number) Limit diagnostics to the given namespace.
----                        - lnum: (number) Limit diagnostics to the given line number.
----                        - severity: See |diagnostic-severity|.
----@return vim.Diagnostic[] table A list of diagnostic items |diagnostic-structure|. Keys `bufnr`, `end_lnum`, `end_col`, and `severity` are guaranteed to be present.
+---                      current buffer or nil for all buffers.
+---@param opts? vim.diagnostic.GetOpts
+---@return vim.Diagnostic[] : Fields `bufnr`, `end_lnum`, `end_col`, and `severity`
+---                           are guaranteed to be present.
 function M.get(bufnr, opts)
   vim.validate({
     bufnr = { bufnr, 'n', true },
@@ -962,11 +1032,9 @@ end
 ---
 ---@param bufnr? integer Buffer number to get diagnostics from. Use 0 for
 ---                      current buffer or nil for all buffers.
----@param opts? table A table with the following keys:
----                   - namespace: (number) Limit diagnostics to the given namespace.
----                   - lnum: (number) Limit diagnostics to the given line number.
----                   - severity: See |diagnostic-severity|.
----@return table A table with actually present severity values as keys (see |diagnostic-severity|) and integer counts as values.
+---@param opts? vim.diagnostic.GetOpts
+---@return table : Table with actually present severity values as keys
+---                (see |diagnostic-severity|) and integer counts as values.
 function M.count(bufnr, opts)
   vim.validate({
     bufnr = { bufnr, 'n', true },
@@ -984,8 +1052,8 @@ end
 
 --- Get the previous diagnostic closest to the cursor position.
 ---
----@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()|
----@return vim.Diagnostic? Previous diagnostic
+---@param opts? vim.diagnostic.GotoOpts
+---@return vim.Diagnostic? : Previous diagnostic
 function M.get_prev(opts)
   opts = opts or {}
 
@@ -998,9 +1066,9 @@ end
 
 --- Return the position of the previous diagnostic in the current buffer.
 ---
----@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()|
----@return table|false: Previous diagnostic position as a (row, col) tuple or false if there is no
----                     prior diagnostic
+---@param opts? vim.diagnostic.GotoOpts
+---@return table|false: Previous diagnostic position as a `(row, col)` tuple
+---                     or `false` if there is no prior diagnostic.
 function M.get_prev_pos(opts)
   local prev = M.get_prev(opts)
   if not prev then
@@ -1011,14 +1079,14 @@ function M.get_prev_pos(opts)
 end
 
 --- Move to the previous diagnostic in the current buffer.
----@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()|
+---@param opts? vim.diagnostic.GotoOpts
 function M.goto_prev(opts)
   return diagnostic_move_pos(opts, M.get_prev_pos(opts))
 end
 
 --- Get the next diagnostic closest to the cursor position.
 ---
----@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()|
+---@param opts? vim.diagnostic.GotoOpts
 ---@return vim.Diagnostic? : Next diagnostic
 function M.get_next(opts)
   opts = opts or {}
@@ -1032,8 +1100,8 @@ end
 
 --- Return the position of the next diagnostic in the current buffer.
 ---
----@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()|
----@return table|false : Next diagnostic position as a (row, col) tuple or false if no next
+---@param opts? vim.diagnostic.GotoOpts
+---@return table|false : Next diagnostic position as a `(row, col)` tuple or false if no next
 ---                      diagnostic.
 function M.get_next_pos(opts)
   local next = M.get_next(opts)
@@ -1046,7 +1114,6 @@ end
 
 --- A table with the following keys:
 --- @class vim.diagnostic.GetOpts
---- @inlinedoc
 ---
 --- Limit diagnostics to the given namespace.
 --- @field namespace? integer
@@ -1059,13 +1126,10 @@ end
 
 --- Configuration table with the following keys:
 --- @class vim.diagnostic.GotoOpts : vim.diagnostic.GetOpts
---- @inlinedoc
----
---- Only consider diagnostics from the given namespace.
---- @field namespace integer
 ---
---- Cursor position as a (row, col) tuple.
---- See |nvim_win_get_cursor()|. Defaults to the current cursor position.
+--- Cursor position as a `(row, col)` tuple.
+--- See |nvim_win_get_cursor()|.
+--- (default: current cursor position)
 --- @field cursor_position? {[1]:integer,[2]:integer}
 ---
 --- Whether to loop around file or not. Similar to 'wrapscan'.
@@ -1075,11 +1139,10 @@ end
 --- See |diagnostic-severity|.
 --- @field severity vim.diagnostic.Severity
 ---
---- If "true", call |vim.diagnostic.open_float()|
---- after moving. If a table, pass the table as the {opts} parameter
---- to |vim.diagnostic.open_float()|. Unless overridden, the float will show
---- diagnostics at the new cursor position (as if "cursor" were passed to
---- the "scope" option).
+--- If `true`, call |vim.diagnostic.open_float()| after moving.
+--- If a table, pass the table as the {opts} parameter to |vim.diagnostic.open_float()|.
+--- Unless overridden, the float will show diagnostics at the new cursor
+--- position (as if "cursor" were passed to the "scope" option).
 --- (default: `true`)
 --- @field float? boolean|vim.diagnostic.Opts.Float
 ---
@@ -1141,7 +1204,7 @@ M.handlers.signs = {
 
     -- Handle legacy diagnostic sign definitions
     -- These were deprecated in 0.10 and will be removed in 0.12
-    if opts.signs and not opts.signs.text and not opts.signs.numhl and not opts.signs.texthl then
+    if opts.signs and not opts.signs.text and not opts.signs.numhl then
       for _, v in ipairs({ 'Error', 'Warn', 'Info', 'Hint' }) do
         local name = string.format('DiagnosticSign%s', v)
         local sign = vim.fn.sign_getdefined(name)[1]
@@ -1476,7 +1539,7 @@ end
 ---                             without saving them or to display only a subset of
 ---                             diagnostics. May not be used when {namespace}
 ---                             or {bufnr} is nil.
----@param opts? vim.diagnostic.Opts (table) Display options. See |vim.diagnostic.config()|.
+---@param opts? vim.diagnostic.Opts Display options.
 function M.show(namespace, bufnr, diagnostics, opts)
   vim.validate({
     namespace = { namespace, 'n', true },
@@ -1552,46 +1615,7 @@ end
 
 --- Show diagnostics in a floating window.
 ---
----@param opts vim.diagnostic.Opts.Float? (table?) 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.
----            - severity_sort: (default false) Sort diagnostics by severity. Overrides the setting
----                             from |vim.diagnostic.config()|.
----            - severity: See |diagnostic-severity|. Overrides the setting
----                        from |vim.diagnostic.config()|.
----            - header: (string or table) String to use as the header for the floating window. If a
----                      table, it is interpreted as a [text, hl_group] tuple. Overrides the setting
----                      from |vim.diagnostic.config()|.
----            - source: (boolean or string) Include the diagnostic source in the message.
----                      Use "if_many" to only show sources if there is more than one source of
----                      diagnostics in the buffer. Otherwise, any truthy value means to always show
----                      the diagnostic source. Overrides the setting from |vim.diagnostic.config()|.
----            - format: (function) A function that takes a diagnostic as input and returns a
----                      string. The 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 function, it must have the signature (diagnostic, i,
----                      total) -> (string, string), where {i} is the index of the diagnostic
----                      being evaluated and {total} is the total number of 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 |vim.diagnostic.config()|.
----            - suffix: Same as {prefix}, but appends the text to the diagnostic instead of
----                      prepending it. Overrides the setting from |vim.diagnostic.config()|.
+---@param opts vim.diagnostic.Opts.Float?
 ---@return integer? float_bufnr
 ---@return integer? win_id
 function M.open_float(opts, ...)
@@ -1963,8 +1987,7 @@ end
 --- WARNING filename:27:3: Variable 'foo' does not exist
 --- ```
 ---
---- This can be parsed into a diagnostic |diagnostic-structure|
---- with:
+--- This can be parsed into |vim.Diagnostic| structure with:
 ---
 --- ```lua
 --- local s = "WARNING filename:27:3: Variable 'foo' does not exist"
@@ -1975,14 +1998,14 @@ end
 ---
 ---@param str string String to parse diagnostics from.
 ---@param pat string Lua pattern with capture groups.
----@param groups string[] List of fields in a |diagnostic-structure| to
+---@param groups string[] List of fields in a |vim.Diagnostic| structure to
 ---                    associate with captures from {pat}.
 ---@param severity_map table A table mapping the severity field from {groups}
 ---                          with an item from |vim.diagnostic.severity|.
 ---@param defaults table? Table of default values for any fields not listed in {groups}.
 ---                       When omitted, numeric values default to 0 and "severity" defaults to
 ---                       ERROR.
----@return vim.Diagnostic?: |diagnostic-structure| or `nil` if {pat} fails to match {str}.
+---@return vim.Diagnostic?: |vim.Diagnostic| structure or `nil` if {pat} fails to match {str}.
 function M.match(str, pat, groups, severity_map, defaults)
   vim.validate({
     str = { str, 's' },
@@ -2030,8 +2053,8 @@ local errlist_type_map = {
 --- Convert a list of diagnostics to a list of quickfix items that can be
 --- passed to |setqflist()| or |setloclist()|.
 ---
----@param diagnostics vim.Diagnostic[] List of diagnostics |diagnostic-structure|.
----@return table[] of quickfix list items |setqflist-what|
+---@param diagnostics vim.Diagnostic[]
+---@return table[] : Quickfix list items |setqflist-what|
 function M.toqflist(diagnostics)
   vim.validate({
     diagnostics = {
@@ -2071,7 +2094,7 @@ end
 --- Convert a list of quickfix items to a list of diagnostics.
 ---
 ---@param list table[] List of quickfix items from |getqflist()| or |getloclist()|.
----@return vim.Diagnostic[] array of |diagnostic-structure|
+---@return vim.Diagnostic[]
 function M.fromqflist(list)
   vim.validate({
     list = {
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index 8ebf4de3cb..ef5d9d7cff 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -961,16 +961,15 @@ end
 ---
 --- Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the result.
 --- Parameters are the same as |vim.lsp.buf_request_all()| but the result is
---- different. Waits a maximum of {timeout_ms} (default 1000) ms.
+--- different. Waits a maximum of {timeout_ms}.
 ---
----@param bufnr (integer) Buffer handle, or 0 for current.
----@param method (string) LSP method name
----@param params (table|nil) Parameters to send to the server
----@param timeout_ms (integer|nil) Maximum time in milliseconds to wait for a
----                               result. Defaults to 1000
----
----@return table<integer, {err: lsp.ResponseError, result: any}>|nil (table) result Map of client_id:request_result.
----@return string|nil err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil.
+---@param bufnr integer Buffer handle, or 0 for current.
+---@param method string LSP method name
+---@param params table? Parameters to send to the server
+---@param timeout_ms integer? Maximum time in milliseconds to wait for a result.
+---                           (default: `1000`)
+---@return table<integer, {err: lsp.ResponseError, result: any}>? result Map of client_id:request_result.
+---@return string? err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil.
 function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
   local request_results
 
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
index 0f47c57cd5..6dd898bea7 100644
--- a/runtime/lua/vim/lsp/client.lua
+++ b/runtime/lua/vim/lsp/client.lua
@@ -11,6 +11,24 @@ local validate = vim.validate
 --- @alias vim.lsp.client.on_exit_cb fun(code: integer, signal: integer, client_id: integer)
 --- @alias vim.lsp.client.before_init_cb fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)
 
+--- @class vim.lsp.Client.Flags
+--- @inlinedoc
+---
+--- Allow using incremental sync for buffer edits
+--- (defailt: `true`)
+--- @field allow_incremental_sync? boolean
+---
+--- Debounce `didChange` notifications to the server by the given number in milliseconds.
+--- No debounce occurs if `nil`.
+--- (default: `150`)
+--- @field debounce_text_changes integer
+---
+--- Milliseconds to wait for server to exit cleanly after sending the
+--- "shutdown" request before sending kill -15. If set to false, nvim exits
+--- immediately after sending the "shutdown" request to the server.
+--- (default: `false`)
+--- @field exit_timeout integer|false
+
 --- @class vim.lsp.ClientConfig
 --- command string[] that launches the language
 --- server (treated as in |jobstart()|, must be absolute or on `$PATH`, shell constructs like
@@ -55,8 +73,8 @@ local validate = vim.validate
 --- Map of language server method names to |lsp-handler|
 --- @field handlers? table<string,function>
 ---
---- Map with language server specific settings. These are returned to the language server if
---- requested via `workspace/configuration`. Keys are case-sensitive.
+--- Map with language server specific settings.
+--- See the {settings} in |vim.lsp.Client|.
 --- @field settings? table
 ---
 --- Table that maps string of clientside commands to user-defined functions.
@@ -87,36 +105,29 @@ local validate = vim.validate
 --- Callback invoked before the LSP "initialize" phase, where `params` contains the parameters
 --- being sent to the server and `config` is the config that was passed to |vim.lsp.start_client()|.
 --- You can use this to modify parameters before they are sent.
---- @field before_init? vim.lsp.client.before_init_cb
+--- @field before_init? fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)
 ---
 --- Callback invoked after LSP "initialize", where `result` is a table of `capabilities`
 --- and anything else the server may send. For example, clangd sends
 --- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was sent to it.
 --- You can only modify the `client.offset_encoding` here before any notifications are sent.
---- @field on_init? elem_or_list<vim.lsp.client.on_init_cb>
+--- @field on_init? elem_or_list<fun(client: vim.lsp.Client, initialize_result: lsp.InitializeResult)>
 ---
 --- Callback invoked on client exit.
 ---   - code: exit code of the process
 ---   - signal: number describing the signal used to terminate (if any)
 ---   - client_id: client handle
---- @field on_exit? elem_or_list<vim.lsp.client.on_exit_cb>
+--- @field on_exit? elem_or_list<fun(code: integer, signal: integer, client_id: integer)>
 ---
 --- Callback invoked when client attaches to a buffer.
---- @field on_attach? elem_or_list<vim.lsp.client.on_attach_cb>
+--- @field on_attach? elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>
 ---
 --- Passed directly to the language server in the initialize request. Invalid/empty values will
 --- (default: "off")
 --- @field trace? 'off'|'messages'|'verbose'
 ---
 --- A table with flags for the client. The current (experimental) flags are:
---- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits
---- - debounce_text_changes (number, default 150): Debounce didChange
----   notifications to the server by the given number in milliseconds. No debounce
----   occurs if nil
---- - exit_timeout (number|boolean, default false): Milliseconds to wait for server to
----   exit cleanly after sending the "shutdown" request before sending kill -15.
----   If set to false, nvim exits immediately after sending the "shutdown" request to the server.
---- @field flags? table
+--- @field flags? vim.lsp.Client.Flags
 ---
 --- Directory where the LSP server will base its workspaceFolders, rootUri, and rootPath on initialization.
 --- @field root_dir? string
@@ -189,8 +200,14 @@ local validate = vim.validate
 --- Client commands take precedence over the global command registry.
 --- @field commands table<string,fun(command: lsp.Command, ctx: table)>
 ---
+--- Map with language server specific settings. These are returned to the
+--- language server if requested via `workspace/configuration`. Keys are
+--- case-sensitive.
 --- @field settings table
---- @field flags table
+---
+--- A table with flags for the client. The current (experimental) flags are:
+--- @field flags vim.lsp.Client.Flags
+---
 --- @field get_language_id fun(bufnr: integer, filetype: string): string
 ---
 --- The capabilities provided by the client (editor or tool)
diff --git a/runtime/lua/vim/lsp/diagnostic.lua b/runtime/lua/vim/lsp/diagnostic.lua
index 6156821093..e4620897ac 100644
--- a/runtime/lua/vim/lsp/diagnostic.lua
+++ b/runtime/lua/vim/lsp/diagnostic.lua
@@ -321,7 +321,7 @@ end
 ---@param _ lsp.ResponseError?
 ---@param result lsp.DocumentDiagnosticReport
 ---@param ctx lsp.HandlerContext
----@param config table Configuration table (see |vim.diagnostic.config()|).
+---@param config vim.diagnostic.Opts Configuration table (see |vim.diagnostic.config()|).
 function M.on_diagnostic(_, result, ctx, config)
   if result == nil or result.kind == 'unchanged' then
     return
diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua
index 92546e8520..20ac0a125f 100644
--- a/runtime/lua/vim/lsp/semantic_tokens.lua
+++ b/runtime/lua/vim/lsp/semantic_tokens.lua
@@ -572,7 +572,7 @@ local M = {}
 ---
 ---@param bufnr integer
 ---@param client_id integer
----@param opts (nil|table) Optional keyword arguments
+---@param opts? table Optional keyword arguments
 ---  - debounce (integer, default: 200): Debounce token requests
 ---        to the server by the given number in milliseconds
 function M.start(bufnr, client_id, opts)
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index ec70630df3..18d7c8b13e 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -102,7 +102,7 @@ end
 --- @param s string String to split
 --- @param sep string Separator or pattern
 --- @param opts? vim.gsplit.Opts Keyword arguments |kwargs|:
---- @return fun():string|nil (function) Iterator over the split components
+--- @return fun():string? : Iterator over the split components
 function vim.gsplit(s, sep, opts)
   local plain --- @type boolean?
   local trimempty = false
@@ -245,8 +245,8 @@ end
 --- Apply a function to all values of a table.
 ---
 ---@generic T
----@param func fun(value: T): any (function) Function
----@param t table<any, T> (table) Table
+---@param func fun(value: T): any Function
+---@param t table<any, T> Table
 ---@return table : Table of transformed values
 function vim.tbl_map(func, t)
   vim.validate({ func = { func, 'c' }, t = { t, 't' } })
@@ -570,8 +570,10 @@ end
 ---
 ---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t table Dict-like table
----@return function # |for-in| iterator over sorted keys and their values
+---@generic T: table, K, V
+---@param t T Dict-like table
+---@return fun(table: table<K, V>, index?: K):K, V # |for-in| iterator over sorted keys and their values
+---@return T
 function vim.spairs(t)
   vim.validate({ t = { t, 't' } })
   --- @cast t table<any,any>
@@ -1018,7 +1020,7 @@ do
   --- - |Ringbuf:clear()|
   ---
   ---@param size integer
-  ---@return vim.Ringbuf ringbuf (table)
+  ---@return vim.Ringbuf ringbuf
   function vim.ringbuf(size)
     local ringbuf = {
       _items = {},
diff --git a/scripts/gen_vimdoc.lua b/scripts/gen_vimdoc.lua
index 8e2ff8193c..22df411a35 100755
--- a/scripts/gen_vimdoc.lua
+++ b/scripts/gen_vimdoc.lua
@@ -536,7 +536,8 @@ local function render_fields_or_params(xs, generics, classes, exclude_types)
 end
 
 --- @param class nvim.luacats.parser.class
-local function render_class(class)
+--- @param classes table<string,nvim.luacats.parser.class>
+local function render_class(class, classes)
   if class.access or class.nodoc or class.inlinedoc then
     return
   end
@@ -548,13 +549,14 @@ local function render_class(class)
   if class.parent then
     local txt = fmt('Extends: |%s|', class.parent)
     table.insert(ret, md_to_vimdoc(txt, INDENTATION, INDENTATION, TEXT_WIDTH))
+    table.insert(ret, '\n')
   end
 
   if class.desc then
     table.insert(ret, md_to_vimdoc(class.desc, INDENTATION, INDENTATION, TEXT_WIDTH))
   end
 
-  local fields_txt = render_fields_or_params(class.fields)
+  local fields_txt = render_fields_or_params(class.fields, nil, classes)
   if not fields_txt:match('^%s*$') then
     table.insert(ret, '\n    Fields: ~\n')
     table.insert(ret, fields_txt)
@@ -564,13 +566,12 @@ local function render_class(class)
   return table.concat(ret)
 end
 
---- @param cls table<string,nvim.luacats.parser.class>
-local function render_classes(cls)
+--- @param classes table<string,nvim.luacats.parser.class>
+local function render_classes(classes)
   local ret = {} --- @type string[]
 
-  --- @diagnostic disable-next-line:no-unknown
-  for _, class in vim.spairs(cls) do
-    ret[#ret + 1] = render_class(class)
+  for _, class in vim.spairs(classes) do
+    ret[#ret + 1] = render_class(class, classes)
   end
 
   return table.concat(ret)
diff --git a/scripts/luacats_grammar.lua b/scripts/luacats_grammar.lua
index 0beb1d2352..158541dc77 100644
--- a/scripts/luacats_grammar.lua
+++ b/scripts/luacats_grammar.lua
@@ -170,7 +170,7 @@ local grammar = P {
   ltype = parenOpt(v.ty_union),
 
   ty_union = v.ty_opt * rep(Pf('|') * v.ty_opt),
-  ty = v.ty_fun + ident + v.ty_table + literal,
+  ty = v.ty_fun + ident + v.ty_table + literal + paren(v.ty),
   ty_param = Pf('<') * comma1(v.ltype) * fill * P('>'),
   ty_opt = v.ty * opt(v.ty_param) * opt(P('[]')) * opt(P('?')),
   ty_index = (Pf('[') * v.ltype * Pf(']')),
diff --git a/test/functional/script/luacats_grammar_spec.lua b/test/functional/script/luacats_grammar_spec.lua
index 931fe42dd0..0fc2e4b95a 100644
--- a/test/functional/script/luacats_grammar_spec.lua
+++ b/test/functional/script/luacats_grammar_spec.lua
@@ -130,4 +130,13 @@ describe('luacats grammar', function()
     type = 'b',
     desc = 'desc',
   })
+
+  test(
+    '@field prefix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)',
+    {
+      kind = 'field',
+      name = 'prefix?',
+      type = 'string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)',
+    }
+  )
 end)