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

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)