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

3 files changed, 31 insertions, 27 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index fe1d6f1645..74c50f00a2 100644
--- a/runtime/doc/deprecated.txt
+++ b/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
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 68f63f4fb8..611f2e0d32 100644
--- a/runtime/doc/lua.txt
+++ b/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.
 
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 5445c4e492..f2875e5646 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/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).