refactor(lsp): use predefined types in util function signatures (#29095)

2 files changed, 55 insertions, 49 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index a78a16968f..c4856c6818 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1832,8 +1832,8 @@ apply_text_document_edit({text_document_edit}, {index}, {offset_encoding})
     document.
 
     Parameters: ~
-      • {text_document_edit}  (`table`) a `TextDocumentEdit` object
-      • {index}               (`integer`) Optional index of the edit, if from
+      • {text_document_edit}  (`lsp.TextDocumentEdit`)
+      • {index}               (`integer?`) Optional index of the edit, if from
                               a list of edits (or nil, if not from a list)
       • {offset_encoding}     (`string?`)
 
@@ -1845,7 +1845,7 @@ apply_text_edits({text_edits}, {bufnr}, {offset_encoding})
     Applies a list of text edits to a buffer.
 
     Parameters: ~
-      • {text_edits}       (`table`) list of `TextEdit` objects
+      • {text_edits}       (`lsp.TextEdit[]`)
       • {bufnr}            (`integer`) Buffer id
       • {offset_encoding}  (`string`) utf-8|utf-16|utf-32
 
@@ -1857,7 +1857,7 @@ apply_workspace_edit({workspace_edit}, {offset_encoding})
     Applies a `WorkspaceEdit`.
 
     Parameters: ~
-      • {workspace_edit}   (`table`) `WorkspaceEdit`
+      • {workspace_edit}   (`lsp.WorkspaceEdit`)
       • {offset_encoding}  (`string`) utf-8|utf-16|utf-32 (required)
 
     See also: ~
@@ -1875,8 +1875,7 @@ buf_highlight_references({bufnr}, {references}, {offset_encoding})
 
     Parameters: ~
       • {bufnr}            (`integer`) Buffer id
-      • {references}       (`table`) List of `DocumentHighlight` objects to
-                           highlight
+      • {references}       (`lsp.DocumentHighlight[]`) objects to highlight
       • {offset_encoding}  (`string`) One of "utf-8", "utf-16", "utf-32".
 
     See also: ~
@@ -1910,8 +1909,8 @@ convert_input_to_markdown_lines({input}, {contents})
 
     Parameters: ~
       • {input}     (`lsp.MarkedString|lsp.MarkedString[]|lsp.MarkupContent`)
-      • {contents}  (`table?`) List of strings to extend with converted lines.
-                    Defaults to {}.
+      • {contents}  (`string[]?`) List of strings to extend with converted
+                    lines. Defaults to {}.
 
     Return: ~
         (`string[]`) extended with lines of converted markdown.
@@ -1924,15 +1923,16 @@ convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers})
     Converts `textDocument/signatureHelp` response to markdown lines.
 
     Parameters: ~
-      • {signature_help}  (`table`) Response of `textDocument/SignatureHelp`
+      • {signature_help}  (`lsp.SignatureHelp`) Response of
+                          `textDocument/SignatureHelp`
       • {ft}              (`string?`) filetype that will be use as the `lang`
                           for the label markdown code block
       • {triggers}        (`table?`) list of trigger characters from the lsp
                           server. used to better determine parameter offsets
 
     Return (multiple): ~
-        (`table?`) table list of lines of converted markdown.
-        (`table?`) table of active hl
+        (`string[]?`) table list of lines of converted markdown.
+        (`number[]?`) table of active hl
 
     See also: ~
       • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
@@ -1954,7 +1954,7 @@ jump_to_location({location}, {offset_encoding}, {reuse_win})
     Jumps to a location.
 
     Parameters: ~
-      • {location}         (`table`) (`Location`|`LocationLink`)
+      • {location}         (`lsp.Location|lsp.LocationLink`)
       • {offset_encoding}  (`string?`) utf-8|utf-16|utf-32
       • {reuse_win}        (`boolean?`) Jump to existing window if buffer is
                            already open.
@@ -2019,7 +2019,8 @@ make_formatting_params({options})
     cursor position.
 
     Parameters: ~
-      • {options}  (`table?`) with valid `FormattingOptions` entries
+      • {options}  (`lsp.FormattingOptions?`) with valid `FormattingOptions`
+                   entries
 
     Return: ~
         (`lsp.DocumentFormattingParams`) object
@@ -2059,7 +2060,7 @@ make_position_params({window}, {offset_encoding})
                            `window`
 
     Return: ~
-        (`table`) `TextDocumentPositionParams` object
+        (`lsp.TextDocumentPositionParams`)
 
     See also: ~
       • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
@@ -2090,7 +2091,7 @@ make_text_document_params({bufnr})
       • {bufnr}  (`integer?`) Buffer handle, defaults to current
 
     Return: ~
-        (`table`) `TextDocumentIdentifier`
+        (`lsp.TextDocumentIdentifier`)
 
     See also: ~
       • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
@@ -2100,8 +2101,11 @@ make_workspace_params({added}, {removed})
     Create the workspace params
 
     Parameters: ~
-      • {added}    (`table`)
-      • {removed}  (`table`)
+      • {added}    (`lsp.WorkspaceFolder[]`)
+      • {removed}  (`lsp.WorkspaceFolder[]`)
+
+    Return: ~
+        (`lsp.WorkspaceFoldersChangeEvent`)
 
                                         *vim.lsp.util.open_floating_preview()*
 open_floating_preview({contents}, {syntax}, {opts})
@@ -2145,7 +2149,7 @@ preview_location({location}, {opts})         *vim.lsp.util.preview_location()*
       definition)
 
     Parameters: ~
-      • {location}  (`table`) a single `Location` or `LocationLink`
+      • {location}  (`lsp.Location|lsp.LocationLink`)
       • {opts}      (`table`)
 
     Return (multiple): ~
@@ -2175,7 +2179,7 @@ show_document({location}, {offset_encoding}, {opts})
     Shows document and optionally jumps to the location.
 
     Parameters: ~
-      • {location}         (`table`) (`Location`|`LocationLink`)
+      • {location}         (`lsp.Location|lsp.LocationLink`)
       • {offset_encoding}  (`string?`) utf-8|utf-16|utf-32
       • {opts}             (`table?`) options
                            • reuse_win (boolean) Jump to existing window if
@@ -2200,7 +2204,7 @@ stylize_markdown({bufnr}, {contents}, {opts})
 
     Parameters: ~
       • {bufnr}     (`integer`)
-      • {contents}  (`table`) of lines to show in window
+      • {contents}  (`string[]`) of lines to show in window
       • {opts}      (`table`) with optional fields
                     • height of floating window
                     • width of floating window
diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index d1f0e97065..b33f6ccf69 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -173,11 +173,11 @@ local _str_byteindex_enc = M._str_byteindex_enc
 --- CAUTION: Changes in-place!
 ---
 ---@deprecated
----@param lines (table) Original list of strings
----@param A (table) Start position; a 2-tuple of {line,col} numbers
----@param B (table) End position; a 2-tuple of {line,col} numbers
----@param new_lines (table) list of strings to replace the original
----@return table The modified {lines} object
+---@param lines string[] Original list of strings
+---@param A [integer, integer] Start position; a 2-tuple of {line,col} numbers
+---@param B [integer, integer] End position; a 2-tuple {line,col} numbers
+---@param new_lines string[] list of strings to replace the original
+---@return string[] The modified {lines} object
 function M.set_lines(lines, A, B, new_lines)
   vim.deprecate('vim.lsp.util.set_lines()', 'nil', '0.12')
   -- 0-indexing to 1-indexing
@@ -343,7 +343,7 @@ local function get_line_byte_from_position(bufnr, position, offset_encoding)
 end
 
 --- Applies a list of text edits to a buffer.
----@param text_edits table list of `TextEdit` objects
+---@param text_edits lsp.TextEdit[]
 ---@param bufnr integer Buffer id
 ---@param offset_encoding string utf-8|utf-16|utf-32
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit
@@ -481,8 +481,8 @@ end
 --- Applies a `TextDocumentEdit`, which is a list of changes to a single
 --- document.
 ---
----@param text_document_edit table: a `TextDocumentEdit` object
----@param index integer: Optional index of the edit, if from a list of edits (or nil, if not from a list)
+---@param text_document_edit lsp.TextDocumentEdit
+---@param index? integer: Optional index of the edit, if from a list of edits (or nil, if not from a list)
 ---@param offset_encoding? string
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit
 function M.apply_text_document_edit(text_document_edit, index, offset_encoding)
@@ -533,6 +533,7 @@ local function path_under_prefix(path, prefix)
 end
 
 --- Get list of buffers whose filename matches the given path prefix (normalized full path)
+---@param prefix string
 ---@return integer[]
 local function get_bufs_with_prefix(prefix)
   prefix = path_components(prefix)
@@ -677,7 +678,7 @@ end
 
 --- Applies a `WorkspaceEdit`.
 ---
----@param workspace_edit table `WorkspaceEdit`
+---@param workspace_edit lsp.WorkspaceEdit
 ---@param offset_encoding string utf-8|utf-16|utf-32 (required)
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit
 function M.apply_workspace_edit(workspace_edit, offset_encoding)
@@ -723,8 +724,8 @@ end
 --- Note that if the input is of type `MarkupContent` and its kind is `plaintext`,
 --- then the corresponding value is returned without further modifications.
 ---
----@param input (lsp.MarkedString | lsp.MarkedString[] | lsp.MarkupContent)
----@param contents (table|nil) List of strings to extend with converted lines. Defaults to {}.
+---@param input lsp.MarkedString|lsp.MarkedString[]|lsp.MarkupContent
+---@param contents string[]|nil List of strings to extend with converted lines. Defaults to {}.
 ---@return string[] extended with lines of converted markdown.
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
 function M.convert_input_to_markdown_lines(input, contents)
@@ -759,11 +760,11 @@ end
 
 --- Converts `textDocument/signatureHelp` response to markdown lines.
 ---
----@param signature_help table Response of `textDocument/SignatureHelp`
+---@param signature_help lsp.SignatureHelp Response of `textDocument/SignatureHelp`
 ---@param ft string|nil filetype that will be use as the `lang` for the label markdown code block
 ---@param triggers table|nil list of trigger characters from the lsp server. used to better determine parameter offsets
----@return table|nil table list of lines of converted markdown.
----@return table|nil table of active hl
+---@return string[]|nil table list of lines of converted markdown.
+---@return number[]|nil table of active hl
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
 function M.convert_signature_help_to_markdown_lines(signature_help, ft, triggers)
   if not signature_help.signatures then
@@ -960,7 +961,7 @@ end
 
 --- Shows document and optionally jumps to the location.
 ---
----@param location table (`Location`|`LocationLink`)
+---@param location lsp.Location|lsp.LocationLink
 ---@param offset_encoding string|nil utf-8|utf-16|utf-32
 ---@param opts table|nil options
 ---        - reuse_win (boolean) Jump to existing window if buffer is already open.
@@ -1017,7 +1018,7 @@ end
 
 --- Jumps to a location.
 ---
----@param location table (`Location`|`LocationLink`)
+---@param location lsp.Location|lsp.LocationLink
 ---@param offset_encoding string|nil utf-8|utf-16|utf-32
 ---@param reuse_win boolean|nil Jump to existing window if buffer is already open.
 ---@return boolean `true` if the jump succeeded
@@ -1038,7 +1039,7 @@ end
 ---   - for Location, range is shown (e.g., function definition)
 ---   - for LocationLink, targetRange is shown (e.g., body of function definition)
 ---
----@param location table a single `Location` or `LocationLink`
+---@param location lsp.Location|lsp.LocationLink
 ---@param opts table
 ---@return integer|nil buffer id of float window
 ---@return integer|nil window id of float window
@@ -1154,7 +1155,7 @@ end
 --- If you want to open a popup with fancy markdown, use `open_floating_preview` instead
 ---
 ---@param bufnr integer
----@param contents table of lines to show in window
+---@param contents string[] of lines to show in window
 ---@param opts table with optional fields
 ---  - height    of floating window
 ---  - width     of floating window
@@ -1669,7 +1670,7 @@ do --[[ References ]]
   --- Shows a list of document highlights for a certain buffer.
   ---
   ---@param bufnr integer Buffer id
-  ---@param references table List of `DocumentHighlight` objects to highlight
+  ---@param references lsp.DocumentHighlight[] objects to highlight
   ---@param offset_encoding string One of "utf-8", "utf-16", "utf-32".
   ---@see https://microsoft.github.io/language-server-protocol/specification/#textDocumentContentChangeEvent
   function M.buf_highlight_references(bufnr, references, offset_encoding)
@@ -1873,7 +1874,7 @@ end
 --- CAUTION: Modifies the input in-place!
 ---
 ---@deprecated
----@param lines table list of lines
+---@param lines string[] list of lines
 ---@return string filetype or "markdown" if it was unchanged.
 function M.try_trim_markdown_code_blocks(lines)
   vim.deprecate('vim.lsp.util.try_trim_markdown_code_blocks()', 'nil', '0.12')
@@ -1898,7 +1899,7 @@ function M.try_trim_markdown_code_blocks(lines)
 end
 
 ---@param window integer|nil: window handle or 0 for current, defaults to current
----@param offset_encoding string utf-8|utf-16|utf-32|nil defaults to `offset_encoding` of first client of buffer of `window`
+---@param offset_encoding? string utf-8|utf-16|utf-32|nil defaults to `offset_encoding` of first client of buffer of `window`
 local function make_position_param(window, offset_encoding)
   window = window or 0
   local buf = api.nvim_win_get_buf(window)
@@ -1919,7 +1920,7 @@ end
 ---
 ---@param window integer|nil: window handle or 0 for current, defaults to current
 ---@param offset_encoding string|nil utf-8|utf-16|utf-32|nil defaults to `offset_encoding` of first client of buffer of `window`
----@return table `TextDocumentPositionParams` object
+---@return lsp.TextDocumentPositionParams
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
 function M.make_position_params(window, offset_encoding)
   window = window or 0
@@ -1932,7 +1933,7 @@ function M.make_position_params(window, offset_encoding)
 end
 
 --- Utility function for getting the encoding of the first LSP client on the given buffer.
----@param bufnr (integer) buffer handle or 0 for current, defaults to current
+---@param bufnr integer buffer handle or 0 for current, defaults to current
 ---@return string encoding first client if there is one, nil otherwise
 function M._get_offset_encoding(bufnr)
   validate({
@@ -2033,15 +2034,16 @@ end
 --- Creates a `TextDocumentIdentifier` object for the current buffer.
 ---
 ---@param bufnr integer|nil: Buffer handle, defaults to current
----@return table `TextDocumentIdentifier`
+---@return lsp.TextDocumentIdentifier
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
 function M.make_text_document_params(bufnr)
   return { uri = vim.uri_from_bufnr(bufnr or 0) }
 end
 
 --- Create the workspace params
----@param added table
----@param removed table
+---@param added lsp.WorkspaceFolder[]
+---@param removed lsp.WorkspaceFolder[]
+---@return lsp.WorkspaceFoldersChangeEvent
 function M.make_workspace_params(added, removed)
   return { event = { added = added, removed = removed } }
 end
@@ -2049,8 +2051,8 @@ end
 --- Returns indentation size.
 ---
 ---@see 'shiftwidth'
----@param bufnr (integer|nil): Buffer handle, defaults to current
----@return (integer) indentation size
+---@param bufnr integer|nil: Buffer handle, defaults to current
+---@return integer indentation size
 function M.get_effective_tabstop(bufnr)
   validate({ bufnr = { bufnr, 'n', true } })
   local bo = bufnr and vim.bo[bufnr] or vim.bo
@@ -2060,7 +2062,7 @@ end
 
 --- Creates a `DocumentFormattingParams` object for the current buffer and cursor position.
 ---
----@param options table|nil with valid `FormattingOptions` entries
+---@param options lsp.FormattingOptions|nil with valid `FormattingOptions` entries
 ---@return lsp.DocumentFormattingParams object
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
 function M.make_formatting_params(options)