refactor(api): deprecate nvim_notify #31938

Problem:
The `nvim_notify` API (note: unrelated to `vim.notify()` Lua API) was
not given any real motivation in https://github.com/neovim/neovim/pull/13843

There are, and were, idiomatic and ergonomic alternatives already.

Solution:
Deprecate `nvim_notify`.

7 files changed, 47 insertions, 51 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 9e84dd40ac..572e5e4267 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1094,17 +1094,6 @@ nvim_load_context({dict})                                *nvim_load_context()*
     Parameters: ~
       • {dict}  |Context| map.
 
-nvim_notify({msg}, {log_level}, {opts})                        *nvim_notify()*
-    Notify the user with a message
-
-    Relays the call to vim.notify . By default forwards your message in the
-    echo area but can be overridden to trigger desktop notifications.
-
-    Parameters: ~
-      • {msg}        Message to display to the user
-      • {log_level}  The log level
-      • {opts}       Reserved for future use.
-
 nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
     Open a terminal instance in a buffer
 
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index dbdb8f541b..4f320aeab3 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -16,6 +16,7 @@ Deprecated features
 DEPRECATED IN 0.11					*deprecated-0.11*
 
 API
+• nvim_notify()		Use |nvim_echo()| or `nvim_exec_lua("vim.notify(...)", ...)` instead.
 • nvim_subscribe()	Plugins must maintain their own "multicast" channels list.
 • nvim_unsubscribe()	Plugins must maintain their own "multicast" channels list.
 • nvim_out_write()	Use |nvim_echo()|.
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index b5d8a0937d..8930f131f6 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -1647,14 +1647,10 @@ function vim.api.nvim_list_wins() end
 --- @return any
 function vim.api.nvim_load_context(dict) end
 
---- Notify the user with a message
----
---- Relays the call to vim.notify . By default forwards your message in the
---- echo area but can be overridden to trigger desktop notifications.
----
---- @param msg string Message to display to the user
---- @param log_level integer The log level
---- @param opts table<string,any> Reserved for future use.
+--- @deprecated
+--- @param msg string
+--- @param log_level integer
+--- @param opts table<string,any>
 --- @return any
 function vim.api.nvim_notify(msg, log_level, opts) end
 
diff --git a/src/nvim/api/deprecated.c b/src/nvim/api/deprecated.c
index 5150aeebec..b9e7d7143a 100644
--- a/src/nvim/api/deprecated.c
+++ b/src/nvim/api/deprecated.c
@@ -1,3 +1,5 @@
+// Island of misfit toys.
+
 #include <stdbool.h>
 #include <stdint.h>
 #include <string.h>
@@ -896,3 +898,22 @@ void nvim_err_writeln(String str)
 {
   write_msg(str, true, true);
 }
+
+/// @deprecated
+///
+/// Use `nvim_echo` or `nvim_exec_lua("vim.notify(...)", ...)` instead.
+///
+/// @param msg        Message to display to the user
+/// @param log_level  The log level
+/// @param opts       Reserved for future use.
+/// @param[out] err   Error details, if any
+Object nvim_notify(String msg, Integer log_level, Dict opts, Arena *arena, Error *err)
+  FUNC_API_SINCE(7) FUNC_API_DEPRECATED_SINCE(13)
+{
+  MAXSIZE_TEMP_ARRAY(args, 3);
+  ADD_C(args, STRING_OBJ(msg));
+  ADD_C(args, INTEGER_OBJ(log_level));
+  ADD_C(args, DICT_OBJ(opts));
+
+  return NLUA_EXEC_STATIC("return vim.notify(...)", args, kRetObject, arena, err);
+}
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index e03a260280..faf6c0567c 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -516,26 +516,6 @@ Object nvim_exec_lua(String code, Array args, Arena *arena, Error *err)
   return nlua_exec(code, args, kRetObject, arena, err);
 }
 
-/// Notify the user with a message
-///
-/// Relays the call to vim.notify . By default forwards your message in the
-/// echo area but can be overridden to trigger desktop notifications.
-///
-/// @param msg        Message to display to the user
-/// @param log_level  The log level
-/// @param opts       Reserved for future use.
-/// @param[out] err   Error details, if any
-Object nvim_notify(String msg, Integer log_level, Dict opts, Arena *arena, Error *err)
-  FUNC_API_SINCE(7)
-{
-  MAXSIZE_TEMP_ARRAY(args, 3);
-  ADD_C(args, STRING_OBJ(msg));
-  ADD_C(args, INTEGER_OBJ(log_level));
-  ADD_C(args, DICT_OBJ(opts));
-
-  return NLUA_EXEC_STATIC("return vim.notify(...)", args, kRetObject, arena, err);
-}
-
 /// Calculates the number of display cells occupied by `text`.
 /// Control characters including [<Tab>] count as one cell.
 ///
diff --git a/test/functional/api/deprecated_spec.lua b/test/functional/api/deprecated_spec.lua
new file mode 100644
index 0000000000..2efcfda873
--- /dev/null
+++ b/test/functional/api/deprecated_spec.lua
@@ -0,0 +1,21 @@
+-- Island of misfit toys.
+--- @diagnostic disable: deprecated
+
+local t = require('test.testutil')
+local n = require('test.functional.testnvim')()
+
+describe('deprecated', function()
+  before_each(n.clear)
+
+  describe('nvim_notify', function()
+    it('can notify a info message', function()
+      n.api.nvim_notify('hello world', 2, {})
+    end)
+
+    it('can be overridden', function()
+      n.command('lua vim.notify = function(...) return 42 end')
+      t.eq(42, n.api.nvim_exec_lua("return vim.notify('Hello world')", {}))
+      n.api.nvim_notify('hello world', 4, {})
+    end)
+  end)
+end)
diff --git a/test/functional/api/vim_spec.lua b/test/functional/api/vim_spec.lua
index e0ab31f702..044213d83a 100644
--- a/test/functional/api/vim_spec.lua
+++ b/test/functional/api/vim_spec.lua
@@ -781,18 +781,6 @@ describe('API', function()
     end)
   end)
 
-  describe('nvim_notify', function()
-    it('can notify a info message', function()
-      api.nvim_notify('hello world', 2, {})
-    end)
-
-    it('can be overridden', function()
-      command('lua vim.notify = function(...) return 42 end')
-      eq(42, api.nvim_exec_lua("return vim.notify('Hello world')", {}))
-      api.nvim_notify('hello world', 4, {})
-    end)
-  end)
-
   describe('nvim_input', function()
     it('Vimscript error: does NOT fail, updates v:errmsg', function()
       local status, _ = pcall(api.nvim_input, ':call bogus_fn()<CR>')