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, 12 deletions

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>')