feat(lua): vim.deprecate() #18320

This is primarily intended to act as documentation for the developer so
they know exactly when and what to remove. This will help prevent the
situation of deprecated code lingering for far too long as developers
don't have to worry if a function is safe to remove.

1 files changed, 21 insertions, 21 deletions

diff --git a/runtime/lua/vim/lsp/diagnostic.lua b/runtime/lua/vim/lsp/diagnostic.lua
index 6a8d6dcad7..28a236cc7e 100644
--- a/runtime/lua/vim/lsp/diagnostic.lua
+++ b/runtime/lua/vim/lsp/diagnostic.lua
@@ -251,7 +251,7 @@ end
 ---@param client_id number
 ---@private
 function M.save(diagnostics, bufnr, client_id)
-  vim.notify_once('vim.lsp.diagnostic.save is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.save', 'vim.diagnostic.set', '0.8' )
   local namespace = M.get_namespace(client_id)
   vim.diagnostic.set(namespace, bufnr, diagnostic_lsp_to_vim(diagnostics, bufnr, client_id))
 end
@@ -265,7 +265,7 @@ end
 ---                        If nil, diagnostics of all clients are included.
 ---@return table with diagnostics grouped by bufnr (bufnr: Diagnostic[])
 function M.get_all(client_id)
-  vim.notify_once('vim.lsp.diagnostic.get_all is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.get_all', 'vim.diagnostic.get', '0.8' )
   local result = {}
   local namespace
   if client_id then
@@ -287,7 +287,7 @@ end
 ---                            Else, return just the diagnostics associated with the client_id.
 ---@param predicate function|nil Optional function for filtering diagnostics
 function M.get(bufnr, client_id, predicate)
-  vim.notify_once('vim.lsp.diagnostic.get is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.get', 'vim.diagnostic.get', '0.8' )
   predicate = predicate or function() return true end
   if client_id == nil then
     local all_diagnostics = {}
@@ -349,7 +349,7 @@ end
 ---@param severity DiagnosticSeverity
 ---@param client_id number the client id
 function M.get_count(bufnr, severity, client_id)
-  vim.notify_once('vim.lsp.diagnostic.get_count is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.get_count', 'vim.diagnostic.get', '0.8' )
   severity = severity_lsp_to_vim(severity)
   local opts = { severity = severity }
   if client_id ~= nil then
@@ -366,7 +366,7 @@ end
 ---@param opts table See |vim.lsp.diagnostic.goto_next()|
 ---@return table Previous diagnostic
 function M.get_prev(opts)
-  vim.notify_once('vim.lsp.diagnostic.get_prev is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.get_prev', 'vim.diagnostic.get_prev', '0.8' )
   if opts then
     if opts.severity then
       opts.severity = severity_lsp_to_vim(opts.severity)
@@ -384,7 +384,7 @@ end
 ---@param opts table See |vim.lsp.diagnostic.goto_next()|
 ---@return table Previous diagnostic position
 function M.get_prev_pos(opts)
-  vim.notify_once('vim.lsp.diagnostic.get_prev_pos is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.get_prev_pos', 'vim.diagnostic.get_prev_pos', '0.8' )
   if opts then
     if opts.severity then
       opts.severity = severity_lsp_to_vim(opts.severity)
@@ -401,7 +401,7 @@ end
 ---
 ---@param opts table See |vim.lsp.diagnostic.goto_next()|
 function M.goto_prev(opts)
-  vim.notify_once('vim.lsp.diagnostic.goto_prev is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.goto_prev', 'vim.diagnostic.goto_prev', '0.8' )
   if opts then
     if opts.severity then
       opts.severity = severity_lsp_to_vim(opts.severity)
@@ -419,7 +419,7 @@ end
 ---@param opts table See |vim.lsp.diagnostic.goto_next()|
 ---@return table Next diagnostic
 function M.get_next(opts)
-  vim.notify_once('vim.lsp.diagnostic.get_next is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.get_next', 'vim.diagnostic.get_next', '0.8' )
   if opts then
     if opts.severity then
       opts.severity = severity_lsp_to_vim(opts.severity)
@@ -437,7 +437,7 @@ end
 ---@param opts table See |vim.lsp.diagnostic.goto_next()|
 ---@return table Next diagnostic position
 function M.get_next_pos(opts)
-  vim.notify_once('vim.lsp.diagnostic.get_next_pos is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.get_next_pos', 'vim.diagnostic.get_next_pos', '0.8' )
   if opts then
     if opts.severity then
       opts.severity = severity_lsp_to_vim(opts.severity)
@@ -452,7 +452,7 @@ end
 ---
 ---@deprecated Prefer |vim.diagnostic.goto_next()|
 function M.goto_next(opts)
-  vim.notify_once('vim.lsp.diagnostic.goto_next is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.goto_next', 'vim.diagnostic.goto_next', '0.8' )
   if opts then
     if opts.severity then
       opts.severity = severity_lsp_to_vim(opts.severity)
@@ -476,7 +476,7 @@ end
 ---             - severity_limit (DiagnosticSeverity):
 ---                 - Limit severity of diagnostics found. E.g. "Warning" means { "Error", "Warning" } will be valid.
 function M.set_signs(diagnostics, bufnr, client_id, _, opts)
-  vim.notify_once('vim.lsp.diagnostic.set_signs is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.set_signs', nil , '0.8' )
   local namespace = M.get_namespace(client_id)
   if opts and not opts.severity and opts.severity_limit then
     opts.severity = {min=severity_lsp_to_vim(opts.severity_limit)}
@@ -497,7 +497,7 @@ end
 ---             - severity_limit (DiagnosticSeverity):
 ---                 - Limit severity of diagnostics found. E.g. "Warning" means { "Error", "Warning" } will be valid.
 function M.set_underline(diagnostics, bufnr, client_id, _, opts)
-  vim.notify_once('vim.lsp.diagnostic.set_underline is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.set_underline', nil , '0.8' )
   local namespace = M.get_namespace(client_id)
   if opts and not opts.severity and opts.severity_limit then
     opts.severity = {min=severity_lsp_to_vim(opts.severity_limit)}
@@ -519,7 +519,7 @@ end
 ---             - severity_limit (DiagnosticSeverity):
 ---                 - Limit severity of diagnostics found. E.g. "Warning" means { "Error", "Warning" } will be valid.
 function M.set_virtual_text(diagnostics, bufnr, client_id, _, opts)
-  vim.notify_once('vim.lsp.diagnostic.set_virtual_text is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.set_virtual_text', nil , '0.8' )
   local namespace = M.get_namespace(client_id)
   if opts and not opts.severity and opts.severity_limit then
     opts.severity = {min=severity_lsp_to_vim(opts.severity_limit)}
@@ -538,7 +538,7 @@ end
 ---@return an array of [text, hl_group] arrays. This can be passed directly to
 ---        the {virt_text} option of |nvim_buf_set_extmark()|.
 function M.get_virtual_text_chunks_for_line(bufnr, _, line_diags, opts)
-  vim.notify_once('vim.lsp.diagnostic.get_virtual_text_chunks_for_line is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.get_virtual_text_chunks_for_line', nil, '0.8' )
   return vim.diagnostic._get_virt_text_chunks(diagnostic_lsp_to_vim(line_diags, bufnr), opts)
 end
 
@@ -556,7 +556,7 @@ end
 ---@param position table|nil The (0,0)-indexed position
 ---@return table {popup_bufnr, win_id}
 function M.show_position_diagnostics(opts, buf_nr, position)
-  vim.notify_once('vim.lsp.diagnostic.show_position_diagnostics is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.show_position_diagnostics', 'vim.diagnostic.open_float', '0.8' )
   opts = opts or {}
   opts.scope = "cursor"
   opts.pos = position
@@ -580,7 +580,7 @@ end
 ---@param client_id number|nil the client id
 ---@return table {popup_bufnr, win_id}
 function M.show_line_diagnostics(opts, buf_nr, line_nr, client_id)
-  vim.notify_once('vim.lsp.diagnostic.show_line_diagnostics is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.show_line_diagnostics', 'vim.diagnostic.open_float', '0.8' )
   opts = opts or {}
   opts.scope = "line"
   opts.pos = line_nr
@@ -604,7 +604,7 @@ end
 ---       client. The default is to redraw diagnostics for all attached
 ---       clients.
 function M.redraw(bufnr, client_id)
-  vim.notify_once('vim.lsp.diagnostic.redraw is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.redraw', 'vim.diagnostic.show', '0.8' )
   bufnr = get_bufnr(bufnr)
   if not client_id then
     return vim.lsp.for_each_buffer_client(bufnr, function(client)
@@ -632,7 +632,7 @@ end
 ---         - {workspace}: (boolean, default true)
 ---             - Set the list with workspace diagnostics
 function M.set_qflist(opts)
-  vim.notify_once('vim.lsp.diagnostic.set_qflist is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.set_qflist', 'vim.diagnostic.setqflist', '0.8' )
   opts = opts or {}
   if opts.severity then
     opts.severity = severity_lsp_to_vim(opts.severity)
@@ -664,7 +664,7 @@ end
 ---         - {workspace}: (boolean, default false)
 ---             - Set the list with workspace diagnostics
 function M.set_loclist(opts)
-  vim.notify_once('vim.lsp.diagnostic.set_loclist is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.set_loclist', 'vim.diagnostic.setloclist', '0.8' )
   opts = opts or {}
   if opts.severity then
     opts.severity = severity_lsp_to_vim(opts.severity)
@@ -692,7 +692,7 @@ end
 -- send diagnostic information and the client will still process it. The
 -- diagnostics are simply not displayed to the user.
 function M.disable(bufnr, client_id)
-  vim.notify_once('vim.lsp.diagnostic.disable is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.disable', 'vim.diagnostic.disable', '0.8' )
   if not client_id then
     return vim.lsp.for_each_buffer_client(bufnr, function(client)
       M.disable(bufnr, client.id)
@@ -713,7 +713,7 @@ end
 ---       client. The default is to enable diagnostics for all attached
 ---       clients.
 function M.enable(bufnr, client_id)
-  vim.notify_once('vim.lsp.diagnostic.enable is deprecated. See :h deprecated', vim.log.levels.WARN)
+  vim.deprecate('vim.lsp.diagnostic.enable', 'vim.diagnostic.enable', '0.8' )
   if not client_id then
     return vim.lsp.for_each_buffer_client(bufnr, function(client)
       M.enable(bufnr, client.id)