feat(lua): vim.deprecate() #18320

This is primarily intended to act as documentation for the developer so
they know exactly when and what to remove. This will help prevent the
situation of deprecated code lingering for far too long as developers
don't have to worry if a function is safe to remove.

1 files changed, 11 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index ed4cc77369..9ae45ab7fb 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1326,6 +1326,17 @@ defer_fn({fn}, {timeout})                                     *vim.defer_fn()*
                 Return: ~
                     timer luv timer object
 
+deprecate({name}, {alternative}, {version}, {plugin})        *vim.deprecate()*
+                Display a deprecation notification to the user.
+
+                Parameters: ~
+                    {name}         string Deprecated function.
+                    {alternative}  string|nil Preferred alternative function.
+                    {version}      string Version in which the deprecated
+                                   function will be removed.
+                    {plugin}       string|nil Plugin name that the function
+                                   will be removed from. Defaults to "Nvim".
+
 inspect({object}, {options})                                   *vim.inspect()*
                 Return a human-readable representation of the given object.