feat(doc): document Lua alternative for vim.fn

AI-assisted: Codex

1 files changed, 411 insertions, 3 deletions

diff --git a/runtime/lua/vim/_meta/vimfn.gen.lua b/runtime/lua/vim/_meta/vimfn.gen.lua
index 19f55259e7..6784ba6cd2 100644
--- a/runtime/lua/vim/_meta/vimfn.gen.lua
+++ b/runtime/lua/vim/_meta/vimfn.gen.lua
@@ -4,6 +4,8 @@
 --
 error('Cannot require a meta file')
 
+--- Lua: Prefer |math.abs()|.
+---
 --- Return the absolute value of {expr}.  When {expr} evaluates to
 --- a |Float| abs() returns a |Float|.  When {expr} can be
 --- converted to a |Number| abs() returns a |Number|.  Otherwise
@@ -20,6 +22,8 @@ error('Cannot require a meta file')
 --- @return number
 function vim.fn.abs(expr) end
 
+--- Lua: Prefer |math.acos()|.
+---
 --- Return the arc cosine of {expr} measured in radians, as a
 --- |Float| in the range of [0, pi].
 --- {expr} must evaluate to a |Float| or a |Number| in the range
@@ -36,6 +40,8 @@ function vim.fn.abs(expr) end
 --- @return number
 function vim.fn.acos(expr) end
 
+--- Lua: Prefer |table.insert()| for lists and `..` for blobs.
+---
 --- Append the item {expr} to |List| or |Blob| {object}.  Returns
 --- the resulting |List| or |Blob|.  Examples: >vim
 ---   let alist = add([1, 2, 3], item)
@@ -51,6 +57,8 @@ function vim.fn.acos(expr) end
 --- @return any # Resulting |List| or |Blob|, or 1 if {object} is not a |List| or a |Blob|.
 function vim.fn.add(object, expr) end
 
+--- Lua: Prefer |bit.band()|.
+---
 --- Bitwise AND on the two arguments.  The arguments are converted
 --- to a number.  A List, Dict or Float argument causes an error.
 --- Also see |or()| and |xor()|.
@@ -72,6 +80,8 @@ vim.fn['and'] = function(expr, expr1) end
 --- @return table
 function vim.fn.api_info() end
 
+--- Lua: Prefer |nvim_buf_set_lines()|.
+---
 --- When {text} is a |List|: Append each item of the |List| as a
 --- text line below line {lnum} in the current buffer.
 --- Otherwise append {text} as one text line below line {lnum} in
@@ -91,6 +101,8 @@ function vim.fn.api_info() end
 --- @return 0|1
 function vim.fn.append(lnum, text) end
 
+--- Lua: Prefer |nvim_buf_set_lines()|.
+---
 --- Like |append()| but append the text in buffer {buf}.
 ---
 --- This function works only for loaded buffers.  First call
@@ -175,6 +187,8 @@ function vim.fn.arglistid(winnr, tabnr) end
 --- @return string|string[]
 function vim.fn.argv(nr, winid) end
 
+--- Lua: Prefer |math.asin()|.
+---
 --- Return the arc sine of {expr} measured in radians, as a |Float|
 --- in the range of [-pi/2, pi/2].
 --- {expr} must evaluate to a |Float| or a |Number| in the range
@@ -200,6 +214,8 @@ function vim.fn.asin(expr) end
 --- @return 0|1
 function vim.fn.assert_beeps(cmd) end
 
+--- Lua: Prefer |assert()| with |vim.deep_equal()|.
+---
 --- When {expected} and {actual} are not equal an error message is
 --- added to |v:errors| and 1 is returned.  Otherwise zero is
 --- returned. |assert-return|
@@ -293,6 +309,8 @@ function vim.fn.assert_exception(error, msg) end
 --- @return 0|1
 function vim.fn.assert_fails(cmd, error, msg, lnum, context) end
 
+--- Lua: Prefer |assert()|.
+---
 --- When {actual} is not false an error message is added to
 --- |v:errors|, like with |assert_equal()|.
 --- The error is in the form "Expected False but got {actual}".
@@ -308,6 +326,8 @@ function vim.fn.assert_fails(cmd, error, msg, lnum, context) end
 --- @return 0|1
 function vim.fn.assert_false(actual, msg) end
 
+--- Lua: Prefer |assert()|.
+---
 --- This asserts number and |Float| values.  When {actual}  is lower
 --- than {lower} or higher than {upper} an error message is added
 --- to |v:errors|.  Also see |assert-return|.
@@ -383,6 +403,8 @@ function vim.fn.assert_notmatch(pattern, actual, msg) end
 --- @return 0|1
 function vim.fn.assert_report(msg) end
 
+--- Lua: Prefer |assert()|.
+---
 --- When {actual} is not true an error message is added to
 --- |v:errors|, like with |assert_equal()|.
 --- Also see |assert-return|.
@@ -396,6 +418,8 @@ function vim.fn.assert_report(msg) end
 --- @return 0|1
 function vim.fn.assert_true(actual, msg) end
 
+--- Lua: Prefer |math.atan()|.
+---
 --- Return the principal value of the arc tangent of {expr}, in
 --- the range [-pi/2, +pi/2] radians, as a |Float|.
 --- {expr} must evaluate to a |Float| or a |Number|.
@@ -410,6 +434,8 @@ function vim.fn.assert_true(actual, msg) end
 --- @return number
 function vim.fn.atan(expr) end
 
+--- Lua: Prefer |math.atan2()|.
+---
 --- Return the arc tangent of {expr1} / {expr2}, measured in
 --- radians, as a |Float| in the range [-pi, pi].
 --- {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
@@ -487,6 +513,8 @@ function vim.fn.browsedir(title, initdir) end
 --- @return integer
 function vim.fn.bufadd(name) end
 
+--- Lua: Prefer |nvim_buf_is_valid()| after resolving {buf} to a bufnr.
+---
 --- Checks whether a buffer with the name or number {buf} exists.
 --- Returns |TRUE| if the buffer exists, |FALSE| otherwise.
 --- If the {buf} argument is a number, buffer numbers are used.
@@ -513,6 +541,8 @@ function vim.fn.bufadd(name) end
 function vim.fn.bufexists(buf) end
 
 --- @deprecated
+--- Lua: Prefer |nvim_buf_is_valid()| after resolving {buf} to a bufnr.
+---
 --- Obsolete name for |bufexists()|.
 ---
 --- @param ... any
@@ -520,6 +550,8 @@ function vim.fn.bufexists(buf) end
 function vim.fn.buffer_exists(...) end
 
 --- @deprecated
+--- Lua: Prefer |nvim_buf_get_name()| after resolving {buf} to a bufnr.
+---
 --- Obsolete name for |bufname()|.
 ---
 --- @param ... any
@@ -527,12 +559,16 @@ function vim.fn.buffer_exists(...) end
 function vim.fn.buffer_name(...) end
 
 --- @deprecated
+--- Lua: Prefer |nvim_get_current_buf()| when omitted, or |nvim_create_buf()| with |nvim_buf_set_name()| for creating; name lookup, "$", "%", "#", and {create} semantics differ.
+---
 --- Obsolete name for |bufnr()|.
 ---
 --- @param ... any
 --- @return integer
 function vim.fn.buffer_number(...) end
 
+--- Lua: Prefer |vim.bo| or |nvim_get_option_value()| after resolving {buf} to a bufnr.
+---
 --- Checks whether a buffer called {buf} exists and is listed
 --- (has the 'buflisted' option set).  Returns |TRUE| if so,
 --- |FALSE| otherwise.
@@ -554,6 +590,8 @@ function vim.fn.buflisted(buf) end
 --- @param buf any
 function vim.fn.bufload(buf) end
 
+--- Lua: Prefer |nvim_buf_is_loaded()| after resolving {buf} to a bufnr.
+---
 --- Checks whether a buffer called {buf} exists and is loaded
 --- (shown in a window or hidden).  Returns |TRUE| if so,
 --- |FALSE| otherwise.
@@ -563,6 +601,8 @@ function vim.fn.bufload(buf) end
 --- @return 0|1
 function vim.fn.bufloaded(buf) end
 
+--- Lua: Prefer |nvim_buf_get_name()| after resolving {buf} to a bufnr.
+---
 --- The result is the name of a buffer.  Mostly as it is displayed
 --- by the `:ls` command, but not using special names such as
 --- "[No Name]".
@@ -597,6 +637,8 @@ function vim.fn.bufloaded(buf) end
 --- @return string
 function vim.fn.bufname(buf) end
 
+--- Lua: Prefer |nvim_get_current_buf()| when omitted, or |nvim_create_buf()| with |nvim_buf_set_name()| for creating; name lookup, "$", "%", "#", and {create} semantics differ.
+---
 --- The result is the number of a buffer, as it is displayed by
 --- the `:ls` command.  For the use of {buf}, see |bufname()|
 --- above.
@@ -619,6 +661,8 @@ function vim.fn.bufname(buf) end
 --- @return integer
 function vim.fn.bufnr(buf, create) end
 
+--- Lua: Prefer |nvim_tabpage_list_wins()| with |nvim_win_get_buf()| after resolving {buf}; only the current tabpage is checked and no-match semantics differ.
+---
 --- Returns the |window-ID| of the first window associated with
 --- buffer {buf}.  For the use of {buf}, see |bufname()| above.
 --- If buffer {buf} doesn't exist or there is no such window, -1
@@ -633,6 +677,8 @@ function vim.fn.bufnr(buf, create) end
 --- @return integer
 function vim.fn.bufwinid(buf) end
 
+--- Lua: Prefer |nvim_tabpage_list_wins()| with |nvim_win_get_buf()| and |nvim_win_get_number()| after resolving {buf}; only the current tabpage is checked and no-match semantics differ.
+---
 --- Like |bufwinid()| but return the window number instead of the
 --- |window-ID|.
 --- If buffer {buf} doesn't exist or there is no such window, -1
@@ -660,6 +706,8 @@ function vim.fn.bufwinnr(buf) end
 --- @return integer
 function vim.fn.byte2line(byte) end
 
+--- Lua: Prefer |vim.str_byteindex()| for string input with `"utf-32"` or `"utf-16"` and `strict_indexing = false`; composing characters and out-of-range semantics differ.
+---
 --- Return byte index of the {nr}th character in the String
 --- {expr}.  Use zero for the first character, it then returns
 --- zero.
@@ -701,6 +749,8 @@ function vim.fn.byte2line(byte) end
 --- @return integer
 function vim.fn.byteidx(expr, nr, utf16) end
 
+--- Lua: Prefer |vim.str_byteindex()| with `"utf-32"` or `"utf-16"` and `strict_indexing = false`.
+---
 --- Like |byteidx()|, except that a composing character is counted
 --- as a separate character.  Example: >vim
 ---   let s = 'e' .. nr2char(0x301)
@@ -731,6 +781,8 @@ function vim.fn.byteidxcomp(expr, nr, utf16) end
 --- @return any
 function vim.fn.call(func, arglist, dict) end
 
+--- Lua: Prefer |math.ceil()|.
+---
 --- Return the smallest integral value greater than or equal to
 --- {expr} as a |Float| (round up).
 --- {expr} must evaluate to a |Float| or a |Number|.
@@ -773,6 +825,8 @@ function vim.fn.chanclose(id, stream) end
 --- @return integer
 function vim.fn.changenr() end
 
+--- Lua: Prefer |nvim_chan_send()| for string data; list input and the return value differ.
+---
 --- Send data to channel {id}. For a job, it writes it to the
 --- stdin of the process. For the stdio channel |channel-stdio|,
 --- it writes to Nvim's stdout.  Returns the number of bytes
@@ -795,6 +849,8 @@ function vim.fn.changenr() end
 --- @return 0|1
 function vim.fn.chansend(id, data) end
 
+--- Lua: Prefer |string.byte()|: only works with ASCII.
+---
 --- Return Number value of the first char in {string}.
 --- Examples: >vim
 ---   echo char2nr(" ")  " returns 32
@@ -828,6 +884,8 @@ function vim.fn.char2nr(string, utf8) end
 --- @return 0|1|2|3|'other'
 function vim.fn.charclass(string) end
 
+--- Lua: Prefer |nvim_win_get_cursor()| with |vim.str_utfindex()| for ".", or |nvim_get_current_line()| with |vim.str_utfindex()| for "$"; marks, list input, and window semantics differ.
+---
 --- Same as |col()| but returns the character index of the column
 --- position given with {expr} instead of the byte position.
 ---
@@ -842,6 +900,8 @@ function vim.fn.charclass(string) end
 --- @return integer
 function vim.fn.charcol(expr, winid) end
 
+--- Lua: Prefer |vim.str_utfindex()| for string input with `"utf-32"` or `"utf-16"` and `strict_indexing = false`; `countcc = false` and out-of-range semantics differ.
+---
 --- Return the character index of the byte at {idx} in {string}.
 --- The index of the first character is zero.
 --- If there are no multibyte characters the returned value is
@@ -882,6 +942,8 @@ function vim.fn.charcol(expr, winid) end
 --- @return integer
 function vim.fn.charidx(string, idx, countcc, utf16) end
 
+--- Lua: Prefer |nvim_set_current_dir()| for the global directory; tab-local, window-local, and return semantics differ.
+---
 --- Changes the current working directory to {dir}.  The scope of
 --- the change is determined as follows:
 --- If {scope} is not present, the current working directory is
@@ -958,6 +1020,8 @@ function vim.fn.clearmatches(win) end
 --- @return table<string,any>
 function vim.fn.cmdcomplete_info() end
 
+--- Lua: Prefer |nvim_win_get_cursor()| for "." (add 1), or Lua `#` on |nvim_get_current_line()| for "$"; marks, list input, and `virtualedit` differ.
+---
 --- Returns the byte index of the column position given with
 --- {expr}.
 --- For accepted positions see |getpos()|.
@@ -1192,6 +1256,8 @@ function vim.fn.complete_info(what) end
 --- @return integer
 function vim.fn.confirm(msg, choices, default, type) end
 
+--- Lua: Prefer |vim.deepcopy()|; deeper than Vimscript |copy()|.
+---
 --- Make a copy of {expr}.  For Numbers and Strings this isn't
 --- different from using {expr} directly.
 --- When {expr} is a |List| a shallow copy is created.  This means
@@ -1206,6 +1272,8 @@ function vim.fn.confirm(msg, choices, default, type) end
 --- @return T
 function vim.fn.copy(expr) end
 
+--- Lua: Prefer |math.cos()|.
+---
 --- Return the cosine of {expr}, measured in radians, as a |Float|.
 --- {expr} must evaluate to a |Float| or a |Number|.
 --- Returns 0.0 if {expr} is not a |Float| or a |Number|.
@@ -1219,6 +1287,8 @@ function vim.fn.copy(expr) end
 --- @return number
 function vim.fn.cos(expr) end
 
+--- Lua: Prefer |math.cosh()|.
+---
 --- Return the hyperbolic cosine of {expr} as a |Float| in the range
 --- [1, inf].
 --- {expr} must evaluate to a |Float| or a |Number|.
@@ -1297,6 +1367,8 @@ function vim.fn.ctxsize() end
 --- @return any
 function vim.fn.cursor(lnum, col, off) end
 
+--- Lua: Prefer |nvim_win_set_cursor()| with `{lnum, col - 1}`; `off`, `curswant`, and failure semantics differ.
+---
 --- Positions the cursor at the column (byte count) {col} in the
 --- line {lnum}.  The first column is one.
 ---
@@ -1332,6 +1404,8 @@ function vim.fn.cursor(lnum, col, off) end
 --- @return any
 function vim.fn.cursor(list) end
 
+--- Lua: Prefer |uv.kill()| with `"sigtrap"` (or `"sigint"` outside MS-Windows); exact semantics differ.
+---
 --- Specifically used to interrupt a program being debugged.  It
 --- will cause process {pid} to get a SIGTRAP.  Behavior for other
 --- processes is undefined.  See |terminal-debug|.
@@ -1344,6 +1418,8 @@ function vim.fn.cursor(list) end
 --- @return any
 function vim.fn.debugbreak(pid) end
 
+--- Lua: Prefer |vim.deepcopy()|.
+---
 --- Make a copy of {expr}.  For Numbers and Strings this isn't
 --- different from using {expr} directly.
 --- When {expr} is a |List| a full copy is created.  This means
@@ -1369,7 +1445,7 @@ function vim.fn.debugbreak(pid) end
 --- @return T
 function vim.fn.deepcopy(expr, noref) end
 
---- Lua: see |vim.fs.rm()|.
+--- Lua: Prefer |vim.fs.rm()|.
 ---
 --- Without {flags} or with {flags} empty: Deletes the file by the
 --- name {fname}.
@@ -1394,6 +1470,8 @@ function vim.fn.deepcopy(expr, noref) end
 --- @return integer
 function vim.fn.delete(fname, flags) end
 
+--- Lua: Prefer |nvim_buf_set_lines()|.
+---
 --- Delete lines {first} to {last} (inclusive) from buffer {buf}.
 --- If {last} is omitted then delete line {first} only.
 --- On success 0 is returned, on failure 1 is returned.
@@ -1587,6 +1665,8 @@ function vim.fn.digraph_set(chars, digraph) end
 --- @return any
 function vim.fn.digraph_setlist(digraphlist) end
 
+--- Lua: Prefer plain Lua emptiness checks, or |vim.tbl_isempty()| for tables.
+---
 --- Return the Number 1 if {expr} is empty, zero otherwise.
 --- - A |List| or |Dictionary| is empty when it does not have any
 ---   items.
@@ -1599,6 +1679,8 @@ function vim.fn.digraph_setlist(digraphlist) end
 --- @return integer
 function vim.fn.empty(expr) end
 
+--- Lua: Prefer |uv.os_environ()| for the full environment table; |vim.env| for keyed access.
+---
 --- Return all of environment variables as dictionary.  You can
 --- check if an environment variable exists like this: >vim
 ---   echo has_key(environ(), 'HOME')
@@ -1677,6 +1759,8 @@ function vim.fn.eventhandler() end
 --- @return 0|1
 function vim.fn.executable(expr) end
 
+--- Lua: Prefer |nvim_exec()| or |vim.cmd()|.
+---
 --- Execute {command} and capture its output.
 --- If {command} is a |String|, returns {command} output.
 --- If {command} is a |List|, returns concatenated outputs.
@@ -1810,6 +1894,8 @@ function vim.fn.exepath(expr) end
 --- @return 0|1
 function vim.fn.exists(expr) end
 
+--- Lua: Prefer |math.exp()|.
+---
 --- Return the exponential of {expr} as a |Float| in the range
 --- [0, inf].
 --- {expr} must evaluate to a |Float| or a |Number|.
@@ -1958,6 +2044,8 @@ function vim.fn.expand(string, nosuf, list) end
 --- @return any
 function vim.fn.expandcmd(string, options) end
 
+--- Lua: Prefer |vim.list_extend()| for lists, or |vim.tbl_extend()| and |vim.tbl_deep_extend()| for dicts; insertion and keep/force/error behavior differ.
+---
 --- {expr1} and {expr2} must be both |Lists| or both
 --- |Dictionaries|.
 ---
@@ -2000,6 +2088,8 @@ function vim.fn.expandcmd(string, options) end
 --- @return any
 function vim.fn.extend(expr1, expr2, expr3) end
 
+--- Lua: Prefer |vim.list_extend()| on a copy for lists, or |vim.tbl_extend()| and |vim.tbl_deep_extend()| for dicts; insertion and keep/force/error behavior differ.
+---
 --- Like |extend()| but instead of adding items to {expr1} a new
 --- List or Dictionary is created and returned.  {expr1} remains
 --- unchanged.
@@ -2010,6 +2100,8 @@ function vim.fn.extend(expr1, expr2, expr3) end
 --- @return any
 function vim.fn.extendnew(expr1, expr2, expr3) end
 
+--- Lua: Prefer |nvim_feedkeys()|.
+---
 --- Characters in {string} are queued for processing as if they
 --- come from a mapping or were typed by the user.
 ---
@@ -2061,12 +2153,16 @@ function vim.fn.extendnew(expr1, expr2, expr3) end
 function vim.fn.feedkeys(string, mode) end
 
 --- @deprecated
+--- Lua: Prefer |uv.fs_access()| with `"R"` and |uv.fs_stat()| to exclude directories.
+---
 --- Obsolete name for |filereadable()|.
 ---
 --- @param file string
 --- @return any
 function vim.fn.file_readable(file) end
 
+--- Lua: Prefer |uv.fs_copyfile()| with `{ excl = true }`; return semantics differ.
+---
 --- Copy the file pointed to by the name {from} to {to}.  The
 --- result is a Number, which is |TRUE| if the file was copied
 --- successfully, and |FALSE| when it failed.
@@ -2080,6 +2176,8 @@ function vim.fn.file_readable(file) end
 --- @return 0|1
 function vim.fn.filecopy(from, to) end
 
+--- Lua: Prefer |uv.fs_access()| with `"R"` and |uv.fs_stat()| to exclude directories.
+---
 --- Returns |TRUE| if {file} exists, can be read, and is not
 --- a directory, else |FALSE|.
 ---
@@ -2100,6 +2198,8 @@ function vim.fn.filecopy(from, to) end
 --- @return 0|1
 function vim.fn.filereadable(file) end
 
+--- Lua: Prefer |uv.fs_access()| with `"W"` and |uv.fs_stat()| if you need Vim's `2` return for directories.
+---
 --- Checks whether a file with the name {file} exists and can
 --- be written.  Returns 1 if so.  If {file} doesn't exist, or
 --- is not writable, the result is 0.  If {file} is a
@@ -2109,6 +2209,8 @@ function vim.fn.filereadable(file) end
 --- @return 0|1
 function vim.fn.filewritable(file) end
 
+--- Lua: Prefer |vim.tbl_filter()| for lists; dicts, strings, and blobs differ.
+---
 --- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
 --- For each item in {expr1} evaluate {expr2} and when the result
 --- is zero or false remove the item from the |List| or
@@ -2166,6 +2268,8 @@ function vim.fn.filewritable(file) end
 --- @return any
 function vim.fn.filter(expr1, expr2) end
 
+--- Lua: Prefer |vim.fs.find()| with `type = 'directory'`; `path`, `count`, and return semantics differ.
+---
 --- Find directory {name} in {path}.  Supports both downwards and
 --- upwards recursive directory searches.  See |file-searching|
 --- for the syntax of {path}.
@@ -2189,6 +2293,8 @@ function vim.fn.filter(expr1, expr2) end
 --- @return string|string[]
 function vim.fn.finddir(name, path, count) end
 
+--- Lua: Prefer |vim.fs.find()|; `path`, `count`, return semantics, and |'suffixesadd'| handling differ.
+---
 --- Just like |finddir()|, but find a file instead of a directory.
 --- Uses 'suffixesadd'.
 --- Example: >vim
@@ -2202,6 +2308,8 @@ function vim.fn.finddir(name, path, count) end
 --- @return string|string[]
 function vim.fn.findfile(name, path, count) end
 
+--- Lua: Prefer `vim.iter(list):flatten():totable()` for a new flattened list; in-place updates and `maxdepth` differ.
+---
 --- Flatten {list} up to {maxdepth} levels.  Without {maxdepth}
 --- the result is a |List| without nesting, as if {maxdepth} is
 --- a very large number.
@@ -2225,6 +2333,8 @@ function vim.fn.findfile(name, path, count) end
 --- @return any[]|0
 function vim.fn.flatten(list, maxdepth) end
 
+--- Lua: Prefer `vim.iter(list):flatten():totable()` for a new flattened list; `maxdepth` differs.
+---
 --- Like |flatten()| but first make a copy of {list}.
 ---
 --- @param list any[]
@@ -2232,6 +2342,8 @@ function vim.fn.flatten(list, maxdepth) end
 --- @return any[]|0
 function vim.fn.flattennew(list, maxdepth) end
 
+--- Lua: Prefer |math.modf()| (first return value).
+---
 --- Convert {expr} to a Number by omitting the part after the
 --- decimal point.
 --- {expr} must evaluate to a |Float| or a |Number|.
@@ -2257,6 +2369,8 @@ function vim.fn.flattennew(list, maxdepth) end
 --- @return any
 function vim.fn.float2nr(expr) end
 
+--- Lua: Prefer |math.floor()|.
+---
 --- Return the largest integral value less than or equal to
 --- {expr} as a |Float| (round down).
 --- {expr} must evaluate to a |Float| or a |Number|.
@@ -2273,6 +2387,8 @@ function vim.fn.float2nr(expr) end
 --- @return any
 function vim.fn.floor(expr) end
 
+--- Lua: Prefer |math.fmod()|.
+---
 --- Return the remainder of {expr1} / {expr2}, even if the
 --- division is not representable.  Returns {expr1} - i * {expr2}
 --- for some integer i such that if {expr2} is non-zero, the
@@ -2293,6 +2409,8 @@ function vim.fn.floor(expr) end
 --- @return any
 function vim.fn.fmod(expr1, expr2) end
 
+--- Lua: Prefer |nvim_cmd()| or |vim.cmd()| with structured arguments to avoid Ex filename escaping.
+---
 --- Escape {string} for use as file name command argument.  All
 --- characters that have a special meaning, such as `'%'` and `'|'`
 --- are escaped with a backslash. For most systems the characters
@@ -2314,6 +2432,8 @@ function vim.fn.fmod(expr1, expr2) end
 --- @return string
 function vim.fn.fnameescape(string) end
 
+--- Lua: Prefer |vim.fs.dirname()|, |vim.fs.basename()|, |vim.fs.abspath()|, and |vim.fs.normalize()| for common path modifiers; modifier coverage differs.
+---
 --- Modify file name {fname} according to {mods}.  {mods} is a
 --- string of characters like it is used for file names on the
 --- command line.  See |filename-modifiers|.
@@ -2402,6 +2522,8 @@ function vim.fn.foldtext() end
 --- @return string
 function vim.fn.foldtextresult(lnum) end
 
+--- Lua: Prefer |pairs()| or |ipairs()|.
+---
 --- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
 --- For each item in {expr1} execute {expr2}.  {expr1} is not
 --- modified; its values may be, as with |:lockvar| 1. |E741|
@@ -2717,6 +2839,8 @@ function vim.fn.getbufinfo(buf) end
 --- @return vim.fn.getbufinfo.ret.item[]
 function vim.fn.getbufinfo(dict) end
 
+--- Lua: Prefer |nvim_buf_get_lines()|.
+---
 --- Return a |List| with the lines starting from {lnum} to {end}
 --- (inclusive) in the buffer {buf}.  If {end} is omitted, a
 --- |List| with only the line {lnum} is returned.  See
@@ -2748,6 +2872,8 @@ function vim.fn.getbufinfo(dict) end
 --- @return string[]
 function vim.fn.getbufline(buf, lnum, end_) end
 
+--- Lua: Prefer |nvim_buf_get_lines()|.
+---
 --- Just like `getbufline()` but only get one line and return it
 --- as a string.
 ---
@@ -2756,6 +2882,8 @@ function vim.fn.getbufline(buf, lnum, end_) end
 --- @return string
 function vim.fn.getbufoneline(buf, lnum) end
 
+--- Lua: Prefer |nvim_buf_get_var()| or |vim.b| after resolving {buf} to a bufnr; option names use |nvim_get_option_value()| or |vim.bo|.
+---
 --- The result is the value of option or local buffer variable
 --- {varname} in buffer {buf}.  Note that the name without "b:"
 --- must be used.
@@ -3154,6 +3282,8 @@ function vim.fn.getcompletion(pat, type, filtered) end
 --- @return string
 function vim.fn.getcompletiontype(pat) end
 
+--- Lua: Prefer |nvim_win_get_cursor()|; return shape, 0-based column, and `curswant`/invalid-window semantics differ.
+---
 --- Get the position of the cursor.  This is like getpos('.'), but
 --- includes an extra "curswant" item in the list:
 ---     [0, lnum, col, off, curswant] ~
@@ -3195,6 +3325,8 @@ function vim.fn.getcurpos(winid) end
 --- @return any
 function vim.fn.getcursorcharpos(winid) end
 
+--- Lua: Prefer |uv.cwd()| for the global working directory; tab-local and window-local scopes differ.
+---
 --- With no arguments, returns the name of the effective
 --- |current-directory|. With {winnr} or {tabnr} the working
 --- directory of that scope is returned, and 'autochdir' is
@@ -3218,6 +3350,8 @@ function vim.fn.getcursorcharpos(winid) end
 --- @return string
 function vim.fn.getcwd(winnr, tabnr) end
 
+--- Lua: Prefer |vim.env|.
+---
 --- Return the value of environment variable {name}.  The {name}
 --- argument is a string, without a leading '$'.  Example: >vim
 ---   myHome = getenv('HOME')
@@ -3245,6 +3379,8 @@ function vim.fn.getenv(name) end
 --- @return string
 function vim.fn.getfontname(name) end
 
+--- Lua: Prefer |uv.fs_stat()|.
+---
 --- Returns the file permissions of the given file {fname} as a
 --- String.  If {fname} does not exist or its directory cannot be
 --- read, an empty string is returned.
@@ -3264,6 +3400,8 @@ function vim.fn.getfontname(name) end
 --- @return string
 function vim.fn.getfperm(fname) end
 
+--- Lua: Prefer |uv.fs_stat()|.
+---
 --- Returns the size in bytes of the given file {fname}.
 --- If {fname} is a directory, 0 is returned.
 --- If the file {fname} can't be found, -1 is returned.
@@ -3274,6 +3412,8 @@ function vim.fn.getfperm(fname) end
 --- @return integer
 function vim.fn.getfsize(fname) end
 
+--- Lua: Prefer |uv.fs_stat()|.
+---
 --- Returns the last modification time ("mtime") of file {fname}.
 --- The value is measured as seconds since 1st Jan 1970, and may
 --- be passed to |strftime()|.  See also
@@ -3284,6 +3424,8 @@ function vim.fn.getfsize(fname) end
 --- @return integer
 function vim.fn.getftime(fname) end
 
+--- Lua: Prefer |uv.fs_stat()|.
+---
 --- Returns a description of the type of file {fname} as a
 --- String.  If {fname} does not exist an empty string is
 --- returned.
@@ -3307,6 +3449,8 @@ function vim.fn.getftime(fname) end
 --- @return 'file'|'dir'|'link'|'bdev'|'cdev'|'socket'|'fifo'|'other'
 function vim.fn.getftype(fname) end
 
+--- Lua: Prefer |nvim_get_context()| for current jump history; window/tab arguments and return shape differ.
+---
 --- Returns the |jumplist| for the specified window.
 ---
 --- Without arguments use the current window.
@@ -3331,6 +3475,8 @@ function vim.fn.getftype(fname) end
 --- @return vim.fn.getjumplist.ret
 function vim.fn.getjumplist(winnr, tabnr) end
 
+--- Lua: Prefer |nvim_get_current_line()| or |nvim_buf_get_lines()|.
+---
 --- Without {end} the result is a String, which is line {lnum}
 --- from the current buffer.  Example: >vim
 ---   getline(1)
@@ -3360,6 +3506,8 @@ function vim.fn.getjumplist(winnr, tabnr) end
 --- @return string
 function vim.fn.getline(lnum, end_) end
 
+--- Lua: Prefer |nvim_get_current_line()| or |nvim_buf_get_lines()|.
+---
 --- @param lnum integer|string
 --- @param end_ true|number|string|table
 --- @return string|string[]
@@ -3491,12 +3639,16 @@ function vim.fn.getmatches(win) end
 --- @return vim.fn.getmousepos.ret
 function vim.fn.getmousepos() end
 
+--- Lua: Prefer |uv.os_getpid()|.
+---
 --- Return a Number which is the process ID of the Vim process.
 --- This is a unique number, until Vim exits.
 ---
 --- @return integer
 function vim.fn.getpid() end
 
+--- Lua: Prefer |nvim_win_get_cursor()| for "." or |nvim_buf_get_mark()| for marks; return shape, `off`, and special-position semantics differ.
+---
 --- Gets a position, where {expr} is one of:
 ---     .      Cursor position.
 ---     $      Last line in the current buffer.
@@ -3887,6 +4039,8 @@ function vim.fn.getregtype(regname) end
 --- @return vim.fn.getscriptinfo.ret[]
 function vim.fn.getscriptinfo(opts) end
 
+--- Lua: Prefer |debug.traceback()|.
+---
 --- Returns the current stack trace of Vim scripts.
 --- Stack trace is a |List|, of which each item is a |Dictionary|
 --- with the following items:
@@ -3917,6 +4071,8 @@ function vim.fn.getstacktrace() end
 --- @return any
 function vim.fn.gettabinfo(tabnr) end
 
+--- Lua: Prefer |nvim_tabpage_get_var()| or |vim.t|.
+---
 --- Get the value of a tab-local variable {varname} in tab page
 --- {tabnr}. |t:var|
 --- Tabs are numbered starting with one.
@@ -3932,6 +4088,8 @@ function vim.fn.gettabinfo(tabnr) end
 --- @return any
 function vim.fn.gettabvar(tabnr, varname, def) end
 
+--- Lua: Prefer |nvim_win_get_var()| or |vim.w| after resolving {tabnr} and {winnr} to a winid; option names use |nvim_get_option_value()| or |vim.wo|.
+---
 --- Get the value of window-local variable {varname} in window
 --- {winnr} in tab page {tabnr}.
 --- The {varname} argument is a string.  When {varname} is empty a
@@ -4089,6 +4247,8 @@ function vim.fn.getwinposx() end
 --- @return integer
 function vim.fn.getwinposy() end
 
+--- Lua: Prefer |nvim_win_get_var()| or |vim.w| after resolving {winnr}; option names use |nvim_get_option_value()| or |vim.wo|.
+---
 --- Like |gettabwinvar()| for the current tabpage.
 --- Examples: >vim
 ---   let list_is_on = getwinvar(2, '&list')
@@ -4278,6 +4438,8 @@ function vim.fn.globpath(path, expr, nosuf, list, allinks) end
 --- @return 0|1
 function vim.fn.has(feature) end
 
+--- Lua: Prefer `dict[key] ~= nil`.
+---
 --- Checks whether |Dictionary| {dict} has an entry with key
 --- {key}.  Returns TRUE if so, FALSE otherwise.  The {key}
 --- argument is a string.
@@ -4345,6 +4507,8 @@ function vim.fn.haslocaldir(winnr, tabnr) end
 function vim.fn.hasmapto(what, mode, abbr) end
 
 --- @deprecated
+--- Lua: Prefer |nvim_get_hl()|.
+---
 --- Obsolete name for |hlID()|.
 ---
 --- @param name string
@@ -4352,6 +4516,8 @@ function vim.fn.hasmapto(what, mode, abbr) end
 function vim.fn.highlightID(name) end
 
 --- @deprecated
+--- Lua: Prefer |nvim_get_hl()|.
+---
 --- Obsolete name for |hlexists()|.
 ---
 --- @param name string
@@ -4452,6 +4618,8 @@ function vim.fn.histget(history, index) end
 --- @return integer
 function vim.fn.histnr(history) end
 
+--- Lua: Prefer |nvim_get_hl()|.
+---
 --- Returns the numeric ID of the highlight group with name
 --- {name}.  When the highlight group doesn't exist, zero is
 --- returned.
@@ -4465,6 +4633,8 @@ function vim.fn.histnr(history) end
 --- @return integer
 function vim.fn.hlID(name) end
 
+--- Lua: Prefer |nvim_get_hl()|.
+---
 --- Checks whether a highlight group called {name} exists.
 --- Returns TRUE if the group has been defined in some way.  Not
 --- necessarily when highlighting has been defined for it, it may
@@ -4474,12 +4644,16 @@ function vim.fn.hlID(name) end
 --- @return 0|1
 function vim.fn.hlexists(name) end
 
+--- Lua: Prefer |uv.os_gethostname()|.
+---
 --- Returns the hostname of the machine on which the Nvim server
 --- (not the UI client) is currently running.
 ---
 --- @return string
 function vim.fn.hostname() end
 
+--- Lua: Prefer |vim.iconv()|.
+---
 --- Converts the encoding of {string} from {from} to {to}.
 --- Returns the converted String.
 --- When the conversion completely fails an empty string is
@@ -4529,6 +4703,8 @@ function vim.fn.id(expr) end
 --- @return integer
 function vim.fn.indent(lnum) end
 
+--- Lua: Prefer |vim.iter()| with |Iter:enumerate()| and |Iter:find()| for lists; result is 1-based, and `start`, `ic`, and Blob semantics differ.
+---
 --- Find {expr} in {object} and return its index.  See
 --- |indexof()| for using a lambda to select the item.
 ---
@@ -4563,6 +4739,8 @@ function vim.fn.indent(lnum) end
 --- @return integer
 function vim.fn.index(object, expr, start, ic) end
 
+--- Lua: Prefer |vim.iter()| with |Iter:enumerate()| and |Iter:find()| for list predicates; result is 1-based, and `startidx` and Blob semantics differ.
+---
 --- Returns the index of an item in {object} where {expr} is
 --- v:true.  {object} must be a |List| or a |Blob|.
 ---
@@ -4607,6 +4785,8 @@ function vim.fn.index(object, expr, start, ic) end
 --- @return integer
 function vim.fn.indexof(object, expr, opts) end
 
+--- Lua: Prefer |vim.ui.input()| for callback-based input.
+---
 ---
 --- @param prompt string
 --- @param text? string
@@ -4614,6 +4794,8 @@ function vim.fn.indexof(object, expr, opts) end
 --- @return string
 function vim.fn.input(prompt, text, completion) end
 
+--- Lua: Prefer |vim.ui.input()| for callback-based input.
+---
 --- Prompts the user to enter text on the command-line, and
 --- returns the text as a String.  The {prompt} argument is either
 --- a prompt string, or a blank string (for no prompt).  A '\n'
@@ -4729,12 +4911,16 @@ function vim.fn.input(prompt, text, completion) end
 function vim.fn.input(opts) end
 
 --- @deprecated
+--- Lua: Prefer |vim.ui.input()| for callback-based input.
+---
 --- Use |input()| instead.
 ---
 --- @param ... any
 --- @return any
 function vim.fn.inputdialog(...) end
 
+--- Lua: Prefer |vim.ui.select()| for simple selection menus; callback, returned item, and out-of-range semantics differ.
+---
 --- Displays a list of strings and prompts the user to select
 --- one by entering a number.  {textlist} must be a |List| of
 --- strings.  Returns the number the user entered.
@@ -4790,6 +4976,8 @@ function vim.fn.inputsave() end
 --- @return string
 function vim.fn.inputsecret(prompt, text) end
 
+--- Lua: Prefer |table.insert()| for lists; blob insertion and negative indexes differ.
+---
 --- When {object} is a |List| or a |Blob| insert {item} at the start
 --- of it.
 ---
@@ -4828,6 +5016,8 @@ function vim.fn.insert(object, item, idx) end
 --- @return any
 function vim.fn.interrupt() end
 
+--- Lua: Prefer |bit.bnot()|.
+---
 --- Bitwise invert.  The argument is converted to a number.  A
 --- List, Dict or Float argument causes an error.  Example: >vim
 ---   let bits = invert(bits)
@@ -4856,6 +5046,8 @@ function vim.fn.invert(expr) end
 --- @return 0|1
 function vim.fn.isabsolutepath(path) end
 
+--- Lua: Prefer |uv.fs_stat()| and check `type == "directory"`.
+---
 --- Returns |TRUE| if {directory} exists, or |FALSE| if it doesn't
 --- exist or isn't a directory.  {directory} is any expression,
 --- which is used as a String.
@@ -4864,6 +5056,8 @@ function vim.fn.isabsolutepath(path) end
 --- @return 0|1
 function vim.fn.isdirectory(directory) end
 
+--- Lua: Prefer `expr == math.huge and 1 or expr == -math.huge and -1 or 0`.
+---
 --- Return 1 if {expr} is a positive infinity, or -1 a negative
 --- infinity, otherwise 0. >vim
 ---   echo isinf(1.0 / 0.0)
@@ -4892,6 +5086,8 @@ function vim.fn.isinf(expr) end
 --- @return 0|1
 function vim.fn.islocked(expr) end
 
+--- Lua: Prefer `expr ~= expr`.
+---
 --- Return |TRUE| if {expr} is a float with value NaN. >vim
 ---   echo isnan(0.0 / 0.0)
 --- <  1
@@ -4900,6 +5096,8 @@ function vim.fn.islocked(expr) end
 --- @return 0|1
 function vim.fn.isnan(expr) end
 
+--- Lua: Prefer |pairs()| or |ipairs()|.
+---
 --- Return a |List| with all key/index and value pairs of {expr}.
 --- Each |List| item is a list with two items:
 --- - for a |Dict|: the key and the value
@@ -4930,6 +5128,8 @@ function vim.fn.items(expr) end
 --- @return any
 function vim.fn.jobclose(...) end
 
+--- Lua: Prefer |vim.system()| object `.pid`; |job-id| and channel semantics differ.
+---
 --- Return the PID (process id) of |job-id| {job}.
 ---
 --- @param job integer
@@ -4947,13 +5147,15 @@ function vim.fn.jobpid(job) end
 function vim.fn.jobresize(job, width, height) end
 
 --- @deprecated
+--- Lua: Prefer |nvim_chan_send()| for string data; list input and the return value differ.
+---
 --- Obsolete name for |chansend()|
 ---
 --- @param ... any
 --- @return any
 function vim.fn.jobsend(...) end
 
---- Lua: Prefer |vim.system()| (unless using `rpc`, `pty`, or `term`).
+--- Lua: Prefer |vim.system()| for simple processes; |RPC|, PTY/term, streaming callbacks, and shell-string behavior differ.
 ---
 --- Spawns {cmd} as a job.
 --- If {cmd} is a List it runs directly (no 'shell').
@@ -5050,6 +5252,8 @@ function vim.fn.jobsend(...) end
 --- @return integer
 function vim.fn.jobstart(cmd, opts) end
 
+--- Lua: Prefer |SystemObj:kill()| on a |vim.system()| object; |job-id| semantics differ.
+---
 --- Stop |job-id| {id} by sending SIGTERM to the job process. If
 --- the process does not terminate after a timeout then SIGKILL
 --- will be sent. When the job terminates its |on_exit| handler
@@ -5063,6 +5267,8 @@ function vim.fn.jobstart(cmd, opts) end
 --- @return integer