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