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

1 files changed, 21 insertions, 0 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);
+}