refactor(lsp): deprecate completion util methods

Relates to https://github.com/neovim/neovim/issues/25272

5 files changed, 12 insertions, 62 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 7a2b29f8c8..7f7c498880 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -144,6 +144,9 @@ LSP FUNCTIONS
 - *vim.lsp.util.trim_empty_lines()*		Use |vim.split()| with `trimempty` instead.
 - *vim.lsp.util.try_trim_markdown_code_blocks()*
 - *vim.lsp.util.set_lines()*
+- *vim.lsp.util.extract_completion_items()*
+- *vim.lsp.util.parse_snippet()*
+- *vim.lsp.util.text_document_completion_list_to_complete_items()*
 
 TREESITTER FUNCTIONS
 - *vim.treesitter.language.require_language()*	Use |vim.treesitter.language.add()|
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 3151a17417..e62a411233 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1711,19 +1711,6 @@ convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers})
     See also: ~
       • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
 
-                                     *vim.lsp.util.extract_completion_items()*
-extract_completion_items({result})
-    Can be used to extract the completion items from a `textDocument/completion` request, which may return one of `CompletionItem[]` , `CompletionList` or null.
-
-    Parameters: ~
-      • {result}  (table) The result of a `textDocument/completion` request
-
-    Return: ~
-        lsp.CompletionItem[] List of completion items
-
-    See also: ~
-      • https://microsoft.github.io/language-server-protocol/specification#textDocument_completion
-
 get_effective_tabstop({bufnr})          *vim.lsp.util.get_effective_tabstop()*
     Returns indentation size.
 
@@ -1925,15 +1912,6 @@ open_floating_preview({contents}, {syntax}, {opts})
         (integer) bufnr of newly created float window
         (integer) winid of newly created float window preview window
 
-parse_snippet({input})                          *vim.lsp.util.parse_snippet()*
-    Parses snippets in a completion entry.
-
-    Parameters: ~
-      • {input}  (string) unparsed snippet
-
-    Return: ~
-        (string) parsed snippet
-
 preview_location({location}, {opts})         *vim.lsp.util.preview_location()*
     Previews a location in a floating window
 
@@ -2002,23 +1980,6 @@ symbols_to_items({symbols}, {bufnr})         *vim.lsp.util.symbols_to_items()*
     Parameters: ~
       • {symbols}  (table) DocumentSymbol[] or SymbolInformation[]
 
-              *vim.lsp.util.text_document_completion_list_to_complete_items()*
-text_document_completion_list_to_complete_items({result}, {prefix})
-    Turns the result of a `textDocument/completion` request into
-    vim-compatible |complete-items|.
-
-    Parameters: ~
-      • {result}  (table) The result of a `textDocument/completion` call, e.g.
-                  from |vim.lsp.buf.completion()|, which may be one of
-                  `CompletionItem[]`, `CompletionList` or `null`
-      • {prefix}  (string) the prefix to filter the completion items
-
-    Return: ~
-        table[] items
-
-    See also: ~
-      • complete-items
-
 
 ==============================================================================
 Lua module: vim.lsp.log                                              *lsp-log*
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 0fe675c285..6f2c6efe54 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -309,6 +309,9 @@ release.
   - |vim.lsp.util.trim_empty_lines()|		Use |vim.split()| with `trimempty` instead.
   - |vim.lsp.util.try_trim_markdown_code_blocks()|
   - |vim.lsp.util.set_lines()|
+  - |vim.lsp.util.extract_completion_items()|
+  - |vim.lsp.util.parse_snippet()|
+  - |vim.lsp.util.text_document_completion_list_to_complete_items()|
 
 • `vim.loop` has been renamed to `vim.uv`.
 
diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index 7ccb8a38b1..32b220746f 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -547,10 +547,12 @@ end
 --- Can be used to extract the completion items from a
 --- `textDocument/completion` request, which may return one of
 --- `CompletionItem[]`, `CompletionList` or null.
+---@deprecated
 ---@param result table The result of a `textDocument/completion` request
 ---@return lsp.CompletionItem[] List of completion items
 ---@see https://microsoft.github.io/language-server-protocol/specification#textDocument_completion
 function M.extract_completion_items(result)
+  vim.deprecate('vim.lsp.util.extract_completion_items', nil, '0.11')
   if type(result) == 'table' and result.items then
     -- result is a `CompletionList`
     return result.items
@@ -606,9 +608,11 @@ end
 
 --- Parses snippets in a completion entry.
 ---
+---@deprecated
 ---@param input string unparsed snippet
 ---@return string parsed snippet
 function M.parse_snippet(input)
+  vim.deprecate('vim.lsp.util.parse_snippet', nil, '0.11')
   local ok, parsed = pcall(function()
     return snippet.parse(input)
   end)
@@ -619,20 +623,10 @@ function M.parse_snippet(input)
   return tostring(parsed)
 end
 
---- According to LSP spec, if the client set `completionItemKind.valueSet`,
---- the client must handle it properly even if it receives a value outside the
---- specification.
----
----@param completion_item_kind (`vim.lsp.protocol.completionItemKind`)
----@return (`vim.lsp.protocol.completionItemKind`)
----@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
-function M._get_completion_item_kind_name(completion_item_kind)
-  return protocol.CompletionItemKind[completion_item_kind] or 'Unknown'
-end
-
 --- Turns the result of a `textDocument/completion` request into vim-compatible
 --- |complete-items|.
 ---
+---@deprecated
 ---@param result table The result of a `textDocument/completion` call, e.g.
 --- from |vim.lsp.buf.completion()|, which may be one of `CompletionItem[]`,
 --- `CompletionList` or `null`
@@ -640,6 +634,7 @@ end
 ---@return table[] items
 ---@see complete-items
 function M.text_document_completion_list_to_complete_items(result, prefix)
+  vim.deprecate('vim.lsp.util.text_document_completion_list_to_complete_items', nil, '0.11')
   return require('vim.lsp._completion')._lsp_to_complete_items(result, prefix)
 end
 
diff --git a/test/functional/plugin/lsp_spec.lua b/test/functional/plugin/lsp_spec.lua
index 8a4a82fa38..3bd8db815d 100644
--- a/test/functional/plugin/lsp_spec.lua
+++ b/test/functional/plugin/lsp_spec.lua
@@ -2769,18 +2769,6 @@ describe('LSP', function()
     end)
   end)
 
-  describe('lsp.util._get_completion_item_kind_name', function()
-    it('returns the name specified by protocol', function()
-      eq("Text", exec_lua("return vim.lsp.util._get_completion_item_kind_name(1)"))
-      eq("TypeParameter", exec_lua("return vim.lsp.util._get_completion_item_kind_name(25)"))
-    end)
-    it('returns the name not specified by protocol', function()
-      eq("Unknown", exec_lua("return vim.lsp.util._get_completion_item_kind_name(nil)"))
-      eq("Unknown", exec_lua("return vim.lsp.util._get_completion_item_kind_name(vim.NIL)"))
-      eq("Unknown", exec_lua("return vim.lsp.util._get_completion_item_kind_name(1000)"))
-    end)
-  end)
-
   describe('lsp.util._get_symbol_kind_name', function()
     it('returns the name specified by protocol', function()
       eq("File", exec_lua("return vim.lsp.util._get_symbol_kind_name(1)"))