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`.

2 files changed, 21 insertions, 20 deletions

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.
 ///