fix(diagnostic): correct type annotations; add Diagnostic type (#21120)

Some functions didn't include the `nil` case in the return type
annotation. This corrects those and also adds a Diagnostic class
definition for the diagnostic.get return type

2 files changed, 50 insertions, 33 deletions

diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index a2bacebc72..07a7d5190f 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -431,7 +431,7 @@ fromqflist({list})                               *vim.diagnostic.fromqflist()*
                 |getloclist()|.
 
     Return: ~
-        array of diagnostics |diagnostic-structure|
+        Diagnostic [] array of |diagnostic-structure|
 
 get({bufnr}, {opts})                                    *vim.diagnostic.get()*
     Get current diagnostics.
@@ -446,7 +446,7 @@ get({bufnr}, {opts})                                    *vim.diagnostic.get()*
                  • severity: See |diagnostic-severity|.
 
     Return: ~
-        (table) A list of diagnostic items |diagnostic-structure|.
+        Diagnostic [] table A list of diagnostic items |diagnostic-structure|.
 
 get_namespace({namespace})                    *vim.diagnostic.get_namespace()*
     Get namespace metadata.
@@ -467,37 +467,39 @@ 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}  (table|nil) See |vim.diagnostic.goto_next()|
 
     Return: ~
-        (table) Next diagnostic
+        Diagnostic|nil Next diagnostic
 
 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}  (table|nil) See |vim.diagnostic.goto_next()|
 
     Return: ~
-        (table) Next diagnostic position as a (row, col) tuple.
+        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}  nil|table See |vim.diagnostic.goto_next()|
 
     Return: ~
-        (table) Previous diagnostic
+        Diagnostic|nil Previous diagnostic
 
 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}  (table|nil) See |vim.diagnostic.goto_next()|
 
     Return: ~
-        (table) Previous diagnostic position as a (row, col) tuple.
+        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.
@@ -537,8 +539,8 @@ hide({namespace}, {bufnr})                             *vim.diagnostic.hide()*
     |vim.diagnostic.disable()|.
 
     Parameters: ~
-      • {namespace}  (number|nil) Diagnostic namespace. When omitted, hide
-                     diagnostics from all namespaces.
+      • {namespace}  (number|nil) Diagnostic namespace. When omitted, hide diagnostics from all
+                     namespaces.
       • {bufnr}      (number|nil) Buffer number, or 0 for current buffer. When
                      omitted, hide diagnostics in all buffers.
 
@@ -571,8 +573,8 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
                         default to 0 and "severity" defaults to ERROR.
 
     Return: ~
-        diagnostic |diagnostic-structure| or `nil` if {pat} fails to match
-        {str}.
+        Diagnostic|nil: |diagnostic-structure| or `nil` if {pat} fails to
+        match {str}.
 
 open_float({opts}, {...})                        *vim.diagnostic.open_float()*
     Show diagnostics in a floating window.
@@ -628,7 +630,7 @@ open_float({opts}, {...})                        *vim.diagnostic.open_float()*
                   from |vim.diagnostic.config()|.
 
     Return: ~
-        tuple ({float_bufnr}, {win_id})
+        number|nil, number|nil: ({float_bufnr}, {win_id})
 
 reset({namespace}, {bufnr})                           *vim.diagnostic.reset()*
     Remove all diagnostics from the given namespace.
@@ -639,8 +641,8 @@ reset({namespace}, {bufnr})                           *vim.diagnostic.reset()*
     re-displayed, use |vim.diagnostic.hide()|.
 
     Parameters: ~
-      • {namespace}  (number|nil) Diagnostic namespace. When omitted, remove
-                     diagnostics from all namespaces.
+      • {namespace}  (number|nil) Diagnostic namespace. When omitted, remove diagnostics from all
+                     namespaces.
       • {bufnr}      (number|nil) Remove diagnostics for the given buffer.
                      When omitted, diagnostics are removed for all buffers.
 
@@ -688,8 +690,8 @@ show({namespace}, {bufnr}, {diagnostics}, {opts})
     Display diagnostics for the given namespace and buffer.
 
     Parameters: ~
-      • {namespace}    (number|nil) Diagnostic namespace. When omitted, show
-                       diagnostics from all namespaces.
+      • {namespace}    (number|nil) Diagnostic namespace. When omitted, show diagnostics from all
+                       namespaces.
       • {bufnr}        (number|nil) Buffer number, or 0 for current buffer.
                        When omitted, show diagnostics in all buffers.
       • {diagnostics}  (table|nil) The diagnostics to display. When omitted,
@@ -709,6 +711,6 @@ toqflist({diagnostics})                            *vim.diagnostic.toqflist()*
       • {diagnostics}  (table) List of diagnostics |diagnostic-structure|.
 
     Return: ~
-        array of quickfix list items |setqflist-what|
+        table[] of quickfix list items |setqflist-what|
 
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index a7fc47a5a8..18df1f1586 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -2,6 +2,7 @@ local api, if_nil = vim.api, vim.F.if_nil
 
 local M = {}
 
+---@enum DiagnosticSeverity
 M.severity = {
   ERROR = 1,
   WARN = 2,
@@ -755,6 +756,18 @@ function M.get_namespaces()
   return vim.deepcopy(all_namespaces)
 end
 
+---@class Diagnostic
+---@field buffer number
+---@field lnum number 0-indexed
+---@field end_lnum nil|number 0-indexed
+---@field col number 0-indexed
+---@field end_col nil|number 0-indexed
+---@field severity DiagnosticSeverity
+---@field message string
+---@field source nil|string
+---@field code nil|string
+---@field user_data nil|any arbitrary data plugins can add
+
 --- Get current diagnostics.
 ---
 ---@param bufnr number|nil Buffer number to get diagnostics from. Use 0 for
@@ -763,7 +776,7 @@ end
 ---                        - namespace: (number) Limit diagnostics to the given namespace.
 ---                        - lnum: (number) Limit diagnostics to the given line number.
 ---                        - severity: See |diagnostic-severity|.
----@return table A list of diagnostic items |diagnostic-structure|.
+---@return Diagnostic[] table A list of diagnostic items |diagnostic-structure|.
 function M.get(bufnr, opts)
   vim.validate({
     bufnr = { bufnr, 'n', true },
@@ -775,8 +788,8 @@ end
 
 --- Get the previous diagnostic closest to the cursor position.
 ---
----@param opts table See |vim.diagnostic.goto_next()|
----@return table Previous diagnostic
+---@param opts nil|table See |vim.diagnostic.goto_next()|
+---@return Diagnostic|nil Previous diagnostic
 function M.get_prev(opts)
   opts = opts or {}
 
@@ -789,8 +802,9 @@ end
 
 --- Return the position of the previous diagnostic in the current buffer.
 ---
----@param opts table See |vim.diagnostic.goto_next()|
----@return table Previous diagnostic position as a (row, col) tuple.
+---@param opts table|nil See |vim.diagnostic.goto_next()|
+---@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
@@ -808,8 +822,8 @@ end
 
 --- Get the next diagnostic closest to the cursor position.
 ---
----@param opts table See |vim.diagnostic.goto_next()|
----@return table Next diagnostic
+---@param opts table|nil See |vim.diagnostic.goto_next()|
+---@return Diagnostic|nil Next diagnostic
 function M.get_next(opts)
   opts = opts or {}
 
@@ -822,8 +836,9 @@ end
 
 --- Return the position of the next diagnostic in the current buffer.
 ---
----@param opts table See |vim.diagnostic.goto_next()|
----@return table Next diagnostic position as a (row, col) tuple.
+---@param opts table|nil See |vim.diagnostic.goto_next()|
+---@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)
   if not next then
@@ -1230,7 +1245,7 @@ end
 ---                      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()|.
----@return tuple ({float_bufnr}, {win_id})
+---@return number|nil, number|nil: ({float_bufnr}, {win_id})
 function M.open_float(opts, ...)
   -- Support old (bufnr, opts) signature
   local bufnr
@@ -1578,7 +1593,7 @@ end
 ---@param defaults table|nil Table of default values for any fields not listed in {groups}.
 ---                          When omitted, numeric values default to 0 and "severity" defaults to
 ---                          ERROR.
----@return diagnostic |diagnostic-structure| or `nil` if {pat} fails to match {str}.
+---@return Diagnostic|nil: |diagnostic-structure| or `nil` if {pat} fails to match {str}.
 function M.match(str, pat, groups, severity_map, defaults)
   vim.validate({
     str = { str, 's' },
@@ -1625,7 +1640,7 @@ local errlist_type_map = {
 --- passed to |setqflist()| or |setloclist()|.
 ---
 ---@param diagnostics table List of diagnostics |diagnostic-structure|.
----@return array of quickfix list items |setqflist-what|
+---@return table[] of quickfix list items |setqflist-what|
 function M.toqflist(diagnostics)
   vim.validate({
     diagnostics = {
@@ -1662,7 +1677,7 @@ end
 ---
 ---@param list table A list of quickfix items from |getqflist()| or
 ---            |getloclist()|.
----@return array of diagnostics |diagnostic-structure|
+---@return Diagnostic[] array of |diagnostic-structure|
 function M.fromqflist(list)
   vim.validate({
     list = {