fix(lua): vim.deprecate() shows ":help deprecated" #22677

Problem:
vim.deprecate() shows ":help deprecated" for third-party plugins. ":help
deprecated" only describes deprecations in Nvim, and is unrelated to any
3rd party deprecations.

Solution:
If `plugin` is specified, don't show  ":help deprecated".

fix #22235

runtime/doc/deprecated.txt

@@ -128,7 +128,7 @@ TREESITTER FUNCTIONS
 						and |TSNode:type()| instead.
 
 LUA
-- *vim.register_keystroke_callback()*	Use |vim.on_key()| instead.
+- vim.register_keystroke_callback()	Use |vim.on_key()| instead.
 - *vim.pretty_print()*			Use |vim.print()| instead.
 
 NORMAL COMMANDS

runtime/doc/lua.txt

@@ -1386,17 +1386,20 @@ defer_fn({fn}, {timeout})                                     *vim.defer_fn()*
 
                                                              *vim.deprecate()*
 deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
-    Display a deprecation notification to the user.
+    Shows a deprecation message to the user.
 
     Parameters: ~
-      • {name}         string Deprecated function.
-      • {alternative}  (string|nil) Preferred alternative function.
-      • {version}      string Version in which the deprecated function will be
+      • {name}         string Deprecated feature (function, API, etc.).
+      • {alternative}  (string|nil) Suggested alternative feature.
+      • {version}      string Version when the deprecated function will be
                        removed.
-      • {plugin}       string|nil Plugin name that the function will be
-                       removed from. Defaults to "Nvim".
+      • {plugin}       string|nil Name of the plugin that owns the deprecated
+                       feature. Defaults to "Nvim".
       • {backtrace}    boolean|nil Prints backtrace. Defaults to true.
 
+    Return: ~
+        Deprecated message, or nil if no message was shown.
+
 inspect({object}, {options})                                   *vim.inspect()*
     Gets a human-readable representation of the given object.
 

runtime/lua/vim/_editor.lua

@@ -518,11 +518,6 @@ do
   end
 end
 
----@private
-function vim.register_keystroke_callback()
-  error('vim.register_keystroke_callback is deprecated, instead use: vim.on_key')
-end
-
 local on_key_cbs = {}
 
 --- Adds Lua function {fn} with namespace id {ns_id} as a listener to every,
@@ -882,27 +877,33 @@ function vim._cs_remote(rcid, server_addr, connect_error, args)
   }
 end
 
---- Display a deprecation notification to the user.
+--- Shows a deprecation message to the user.
 ---
----@param name        string     Deprecated function.
----@param alternative string|nil Preferred alternative function.
----@param version     string     Version in which the deprecated function will
----                              be removed.
----@param plugin      string|nil Plugin name that the function will be removed
----                              from. Defaults to "Nvim".
+---@param name        string     Deprecated feature (function, API, etc.).
+---@param alternative string|nil Suggested alternative feature.
+---@param version     string     Version when the deprecated function will be removed.
+---@param plugin      string|nil Name of the plugin that owns the deprecated feature.
+---                              Defaults to "Nvim".
 ---@param backtrace   boolean|nil Prints backtrace. Defaults to true.
+---
+---@returns Deprecated message, or nil if no message was shown.
 function vim.deprecate(name, alternative, version, plugin, backtrace)
-  local message = name .. ' is deprecated'
+  local msg = ('%s is deprecated'):format(name)
   plugin = plugin or 'Nvim'
-  message = alternative and (message .. ', use ' .. alternative .. ' instead.') or message
-  message = message
-    .. ' See :h deprecated\nThis function will be removed in '
-    .. plugin
-    .. ' version '
-    .. version
-  if vim.notify_once(message, vim.log.levels.WARN) and backtrace ~= false then
+  msg = alternative and ('%s, use %s instead.'):format(msg, alternative) or msg
+  msg = ('%s%s\nThis feature will be removed in %s version %s'):format(
+    msg,
+    (plugin == 'Nvim' and ' :help deprecated' or ''),
+    plugin,
+    version
+  )
+  local displayed = vim.notify_once(msg, vim.log.levels.WARN)
+  if displayed and backtrace ~= false then
     vim.notify(debug.traceback('', 2):sub(2), vim.log.levels.WARN)
   end
+  if displayed then
+    return msg
+  end
 end
 
 --- Create builtin mappings (incl. menus).

test/functional/lua/vim_spec.lua

@@ -127,6 +127,22 @@ describe('lua stdlib', function()
     eq(1, funcs.luaeval('vim.stricmp("\\0C\\0", "\\0B\\0")'))
   end)
 
+  it('vim.deprecate', function()
+    -- vim.deprecate(name, alternative, version, plugin, backtrace)
+    eq(dedent[[
+      foo.bar() is deprecated, use zub.wooo{ok=yay} instead. :help deprecated
+      This feature will be removed in Nvim version 2.17]],
+      exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '2.17'))
+    -- Same message, skipped.
+    eq(vim.NIL,
+      exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '2.17'))
+    -- When `plugin` is specified, don't show ":help deprecated". #22235
+    eq(dedent[[
+      foo.bar() is deprecated, use zub.wooo{ok=yay} instead.
+      This feature will be removed in my-plugin.nvim version 0.3.0]],
+      exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '0.3.0', 'my-plugin.nvim', false))
+  end)
+
   it('vim.startswith', function()
     eq(true, funcs.luaeval('vim.startswith("123", "1")'))
     eq(true, funcs.luaeval('vim.startswith("123", "")'))