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

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
 

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()|.

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