docs: no meta info for deprecated functions

A central tenet of our deprecation strategy is that deprecated functions
must have zero footprint in docs, auto-completion, and meta structures.

runtime/lua/vim/_meta/api.lua

@@ -286,10 +286,6 @@ function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end
 function vim.api.nvim_buf_call(buffer, fun) end
 
 --- @deprecated
---- @param buffer integer
---- @param ns_id integer
---- @param line_start integer
---- @param line_end integer
 function vim.api.nvim_buf_clear_highlight(buffer, ns_id, line_start, line_end) end
 
 --- Clears `namespace`d objects (highlights, `extmarks`, virtual text) from
@@ -493,7 +489,6 @@ function vim.api.nvim_buf_get_mark(buffer, name) end
 function vim.api.nvim_buf_get_name(buffer) end
 
 --- @deprecated
---- @param buffer integer
 --- @return integer
 function vim.api.nvim_buf_get_number(buffer) end
 
@@ -513,8 +508,6 @@ function vim.api.nvim_buf_get_number(buffer) end
 function vim.api.nvim_buf_get_offset(buffer, index) end
 
 --- @deprecated
---- @param buffer integer
---- @param name string
 --- @return any
 function vim.api.nvim_buf_get_option(buffer, name) end
 
@@ -755,9 +748,6 @@ function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end
 function vim.api.nvim_buf_set_name(buffer, name) end
 
 --- @deprecated
---- @param buffer integer
---- @param name string
---- @param value any
 function vim.api.nvim_buf_set_option(buffer, name, value) end
 
 --- Sets (replaces) a range in the buffer
@@ -794,11 +784,6 @@ function vim.api.nvim_buf_set_text(buffer, start_row, start_col, end_row, end_co
 function vim.api.nvim_buf_set_var(buffer, name, value) end
 
 --- @deprecated
---- @param buffer integer
---- @param src_id integer
---- @param line integer
---- @param chunks any[]
---- @param opts vim.api.keyset.empty
 --- @return integer
 function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) end
 
@@ -895,7 +880,6 @@ function vim.api.nvim_command(command) end
 
 --- @deprecated
 --- @see vim.api.nvim_exec2
---- @param command string
 --- @return string
 function vim.api.nvim_command_output(command) end
 
@@ -1157,8 +1141,6 @@ function vim.api.nvim_eval_statusline(str, opts) end
 
 --- @deprecated
 --- @see vim.api.nvim_exec2
---- @param src string
---- @param output boolean
 --- @return string
 function vim.api.nvim_exec(src, output) end
 
@@ -1384,15 +1366,11 @@ function vim.api.nvim_get_hl(ns_id, opts) end
 
 --- @deprecated
 --- @see vim.api.nvim_get_hl_by_name
---- @param hl_id integer
---- @param rgb boolean
 --- @return table<string,any>
 function vim.api.nvim_get_hl_by_id(hl_id, rgb) end
 
 --- @deprecated
 --- @see vim.api.nvim_get_hl_by_id
---- @param name string
---- @param rgb boolean
 --- @return table<string,any>
 function vim.api.nvim_get_hl_by_name(name, rgb) end
 
@@ -1449,12 +1427,10 @@ function vim.api.nvim_get_mode() end
 function vim.api.nvim_get_namespaces() end
 
 --- @deprecated
---- @param name string
 --- @return any
 function vim.api.nvim_get_option(name) end
 
 --- @deprecated
---- @param name string
 --- @return vim.api.keyset.get_option_info
 function vim.api.nvim_get_option_info(name) end
 
@@ -2243,8 +2219,6 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end
 function vim.api.nvim_set_keymap(mode, lhs, rhs, opts) end
 
 --- @deprecated
---- @param name string
---- @param value any
 function vim.api.nvim_set_option(name, value) end
 
 --- Sets the value of an option. The behavior of this function matches that of
@@ -2395,8 +2369,6 @@ function vim.api.nvim_win_get_height(window) end
 function vim.api.nvim_win_get_number(window) end
 
 --- @deprecated
---- @param window integer
---- @param name string
 --- @return any
 function vim.api.nvim_win_get_option(window, name) end
 
@@ -2484,9 +2456,6 @@ function vim.api.nvim_win_set_height(window, height) end
 function vim.api.nvim_win_set_hl_ns(window, ns_id) end
 
 --- @deprecated
---- @param window integer
---- @param name string
---- @param value any
 function vim.api.nvim_win_set_option(window, name, value) end
 
 --- Sets a window-scoped (w:) variable

runtime/lua/vim/_meta/vimfn.lua

@@ -510,24 +510,12 @@ function vim.fn.bufadd(name) end
 function vim.fn.bufexists(buf) end
 
 --- @deprecated
---- Obsolete name for |bufexists()|.
----
---- @param ... any
---- @return 0|1
 function vim.fn.buffer_exists(...) end
 
 --- @deprecated
---- Obsolete name for |bufname()|.
----
---- @param ... any
---- @return string
 function vim.fn.buffer_name(...) end
 
 --- @deprecated
---- Obsolete name for |bufnr()|.
----
---- @param ... any
---- @return integer
 function vim.fn.buffer_number(...) end
 
 --- The result is a Number, which is |TRUE| if a buffer called
@@ -1993,10 +1981,6 @@ function vim.fn.extendnew(expr1, expr2, expr3) end
 function vim.fn.feedkeys(string, mode) end
 
 --- @deprecated
---- Obsolete name for |filereadable()|.
----
---- @param file string
---- @return any
 function vim.fn.file_readable(file) end
 
 --- Copy the file pointed to by the name {from} to {to}. The
@@ -4203,17 +4187,9 @@ function vim.fn.haslocaldir(winnr, tabnr) end
 function vim.fn.hasmapto(what, mode, abbr) end
 
 --- @deprecated
---- Obsolete name for |hlID()|.
----
---- @param name string
---- @return any
 function vim.fn.highlightID(name) end
 
 --- @deprecated
---- Obsolete name for |hlexists()|.
----
---- @param name string
---- @return any
 function vim.fn.highlight_exists(name) end
 
 --- Add the String {item} to the history {history} which can be
@@ -4587,10 +4563,6 @@ function vim.fn.input(prompt, text, completion) end
 function vim.fn.input(opts) end
 
 --- @deprecated
---- Use |input()| instead.
----
---- @param ... any
---- @return any
 function vim.fn.inputdialog(...) end
 
 --- {textlist} must be a |List| of strings.  This |List| is
@@ -4774,10 +4746,6 @@ function vim.fn.isnan(expr) end
 function vim.fn.items(dict) end
 
 --- @deprecated
---- Obsolete name for |chanclose()|
----
---- @param ... any
---- @return any
 function vim.fn.jobclose(...) end
 
 --- Return the PID (process id) of |job-id| {job}.
@@ -4797,10 +4765,6 @@ function vim.fn.jobpid(job) end
 function vim.fn.jobresize(job, width, height) end
 
 --- @deprecated
---- Obsolete name for |chansend()|
----
---- @param ... any
---- @return any
 function vim.fn.jobsend(...) end
 
 --- Note: Prefer |vim.system()| in Lua (unless using the `pty` option).
@@ -4997,9 +4961,6 @@ function vim.fn.keys(dict) end
 function vim.fn.keytrans(string) end
 
 --- @deprecated
---- Obsolete name for bufnr("$").
----
---- @return any
 function vim.fn.last_buffer_nr() end
 
 --- The result is a Number, which is the length of the argument.
@@ -7261,25 +7222,9 @@ function vim.fn.rpcnotify(channel, event, args) end
 function vim.fn.rpcrequest(channel, method, args) end
 
 --- @deprecated
---- Deprecated. Replace  >vim
----   let id = rpcstart('prog', ['arg1', 'arg2'])
---- <with >vim
----   let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true})
---- <
----
---- @param prog string
---- @param argv? any
---- @return any
 function vim.fn.rpcstart(prog, argv) end
 
 --- @deprecated
---- Use |jobstop()| instead to stop any job, or
---- `chanclose(id, "rpc")` to close RPC communication
---- without stopping the job. Use chanclose(id) to close
---- any socket.
----
---- @param ... any
---- @return any
 function vim.fn.rpcstop(...) end
 
 --- Evaluate Ruby expression {expr} and return its result

scripts/gen_eval_files.lua

@@ -390,8 +390,10 @@ local function render_api_meta(_f, fun, write)
   local params = process_params(fun.params)
   for _, p in ipairs(params) do
     param_names[#param_names + 1] = p[1]
-    local pdesc = p[3]
-    if pdesc then
+    local pdesc = not fun.deprecated and p[3] or nil
+    if fun.deprecated then -- luacheck: ignore 542
+      -- Skip @param description for deprecated functions.
+    elseif pdesc then
       local s = '--- @param ' .. p[1] .. ' ' .. p[2] .. ' '
       local pdesc_a = split(vim.trim(norm_text(pdesc)))
       write(s .. pdesc_a[1])
@@ -478,10 +480,11 @@ local function render_eval_meta(f, fun, write)
   write('')
   if fun.deprecated then
     write('--- @deprecated')
+    write(render_fun_sig(funname, params))
+    return
   end
 
   local desc = fun.desc
-
   if desc then
     --- @type string
     desc = desc:gsub('\n%s*\n%s*$', '\n')
@@ -492,7 +495,6 @@ local function render_eval_meta(f, fun, write)
   end
 
   local req_args = type(fun.args) == 'table' and fun.args[1] or fun.args or 0
-
   for i, param in ipairs(params) do
     local pname, ptype = param[1], param[2]
     local optional = (pname ~= '...' and i > req_args) and '?' or ''