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

AI-assisted: Codex

1 files changed, 407 insertions, 8 deletions

diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index f8cf01f8a3..84f0d7b91e 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -17,6 +17,10 @@
 --- @field params [string, string, string][]
 --- @field notes? string[]
 --- @field see? string[]
+---
+--- Recommended alternatives if calling from Lua.
+--- `false` means there is no useful Lua replacement to suggest.
+--- @field see_lua? string[]|false
 --- @field lua? false Do not render type information
 --- @field tags? string[] Extra tags
 --- @field data? string Used by gen_eval.lua
@@ -52,6 +56,7 @@ M.funcs = {
     params = { { 'expr', 'number' } },
     signature = 'abs({expr})',
     returns = 'number',
+    see_lua = { '|math.abs()|' },
   },
   acos = {
     args = 1,
@@ -75,6 +80,7 @@ M.funcs = {
     params = { { 'expr', 'number' } },
     returns = 'number',
     signature = 'acos({expr})',
+    see_lua = { '|math.acos()|' },
   },
   add = {
     args = 2,
@@ -96,6 +102,7 @@ M.funcs = {
     returns = 'any',
     returns_desc = [=[Resulting |List| or |Blob|, or 1 if {object} is not a |List| or a |Blob|.]=],
     signature = 'add({object}, {expr})',
+    see_lua = { '|table.insert()| for lists and `..` for blobs' },
   },
   ['and'] = {
     args = 2,
@@ -112,6 +119,7 @@ M.funcs = {
     params = { { 'expr', 'number' }, { 'expr', 'number' } },
     returns = 'integer',
     signature = 'and({expr}, {expr})',
+    see_lua = { '|bit.band()|' },
   },
   api_info = {
     desc = [=[
@@ -150,6 +158,7 @@ M.funcs = {
     params = { { 'lnum', 'integer|string' }, { 'text', 'string|string[]' } },
     returns = '0|1',
     signature = 'append({lnum}, {text})',
+    see_lua = { '|nvim_buf_set_lines()|' },
   },
   appendbufline = {
     args = 3,
@@ -180,6 +189,7 @@ M.funcs = {
     params = { { 'buf', 'integer|string' }, { 'lnum', 'integer' }, { 'text', 'string' } },
     returns = '0|1',
     signature = 'appendbufline({buf}, {lnum}, {text})',
+    see_lua = { '|nvim_buf_set_lines()|' },
   },
   argc = {
     args = { 0, 1 },
@@ -275,6 +285,7 @@ M.funcs = {
     params = { { 'expr', 'any' } },
     returns = 'number',
     signature = 'asin({expr})',
+    see_lua = { '|math.asin()|' },
   },
   assert_beeps = {
     args = 1,
@@ -316,6 +327,7 @@ M.funcs = {
     params = { { 'expected', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } },
     returns = '0|1',
     signature = 'assert_equal({expected}, {actual} [, {msg}])',
+    see_lua = { '|assert()| with |vim.deep_equal()|' },
   },
   assert_equalfile = {
     args = { 2, 3 },
@@ -353,6 +365,7 @@ M.funcs = {
     params = { { 'error', 'any' }, { 'msg', 'any' } },
     returns = '0|1',
     signature = 'assert_exception({error} [, {msg}])',
+    see_lua = false,
   },
   assert_fails = {
     args = { 1, 5 },
@@ -402,6 +415,7 @@ M.funcs = {
     },
     returns = '0|1',
     signature = 'assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])',
+    see_lua = false,
   },
   assert_false = {
     args = { 1, 2 },
@@ -422,6 +436,7 @@ M.funcs = {
     params = { { 'actual', 'any' }, { 'msg', 'any' } },
     returns = '0|1',
     signature = 'assert_false({actual} [, {msg}])',
+    see_lua = { '|assert()|' },
   },
   assert_inrange = {
     args = { 3, 4 },
@@ -443,6 +458,7 @@ M.funcs = {
     },
     returns = '0|1',
     signature = 'assert_inrange({lower}, {upper}, {actual} [, {msg}])',
+    see_lua = { '|assert()|' },
   },
   assert_match = {
     args = { 2, 3 },
@@ -545,6 +561,7 @@ M.funcs = {
     params = { { 'actual', 'any' }, { 'msg', 'string' } },
     returns = '0|1',
     signature = 'assert_true({actual} [, {msg}])',
+    see_lua = { '|assert()|' },
   },
   atan = {
     args = 1,
@@ -566,6 +583,7 @@ M.funcs = {
     params = { { 'expr', 'number' } },
     returns = 'number',
     signature = 'atan({expr})',
+    see_lua = { '|math.atan()|' },
   },
   atan2 = {
     args = 2,
@@ -587,6 +605,7 @@ M.funcs = {
     params = { { 'expr1', 'number' }, { 'expr2', 'number' } },
     returns = 'number',
     signature = 'atan2({expr1}, {expr2})',
+    see_lua = { '|math.atan2()|' },
   },
   blob2list = {
     args = 1,
@@ -604,6 +623,7 @@ M.funcs = {
     params = { { 'blob', 'any' } },
     returns = 'any[]',
     signature = 'blob2list({blob})',
+    see_lua = false,
   },
   browse = {
     args = 4,
@@ -668,6 +688,7 @@ M.funcs = {
     params = { { 'name', 'string' } },
     returns = 'integer',
     signature = 'bufadd({name})',
+    see_lua = false,
   },
   bufexists = {
     args = 1,
@@ -699,6 +720,7 @@ M.funcs = {
     params = { { 'buf', 'any' } },
     returns = '0|1',
     signature = 'bufexists({buf})',
+    see_lua = { '|nvim_buf_is_valid()| after resolving {buf} to a bufnr' },
   },
   buffer_exists = {
     args = 1,
@@ -712,6 +734,7 @@ M.funcs = {
     params = VARARGS,
     returns = '0|1',
     signature = 'buffer_exists({buf})',
+    see_lua = { '|nvim_buf_is_valid()| after resolving {buf} to a bufnr' },
   },
   buffer_name = {
     args = { 0, 1 },
@@ -725,6 +748,7 @@ M.funcs = {
     params = VARARGS,
     returns = 'string',
     signature = 'buffer_name([{buf}])',
+    see_lua = { '|nvim_buf_get_name()| after resolving {buf} to a bufnr' },
   },
   buffer_number = {
     args = { 0, 1 },
@@ -738,6 +762,9 @@ M.funcs = {
     params = VARARGS,
     returns = 'integer',
     signature = 'buffer_number([{buf} [, {create}]])',
+    see_lua = {
+      '|nvim_get_current_buf()| when omitted, or |nvim_create_buf()| with |nvim_buf_set_name()| for creating; name lookup, "$", "%", "#", and {create} semantics differ',
+    },
   },
   buflisted = {
     args = 1,
@@ -753,6 +780,7 @@ M.funcs = {
     params = { { 'buf', 'any' } },
     returns = '0|1',
     signature = 'buflisted({buf})',
+    see_lua = { '|vim.bo| or |nvim_get_option_value()| after resolving {buf} to a bufnr' },
   },
   bufload = {
     args = 1,
@@ -787,6 +815,7 @@ M.funcs = {
     params = { { 'buf', 'any' } },
     returns = '0|1',
     signature = 'bufloaded({buf})',
+    see_lua = { '|nvim_buf_is_loaded()| after resolving {buf} to a bufnr' },
   },
   bufname = {
     args = { 0, 1 },
@@ -826,6 +855,7 @@ M.funcs = {
     params = { { 'buf', 'integer|string' } },
     returns = 'string',
     signature = 'bufname([{buf}])',
+    see_lua = { '|nvim_buf_get_name()| after resolving {buf} to a bufnr' },
   },
   bufnr = {
     args = { 0, 2 },
@@ -853,6 +883,9 @@ M.funcs = {
     params = { { 'buf', 'integer|string' }, { 'create', 'any' } },
     returns = 'integer',
     signature = 'bufnr([{buf} [, {create}]])',
+    see_lua = {
+      '|nvim_get_current_buf()| when omitted, or |nvim_create_buf()| with |nvim_buf_set_name()| for creating; name lookup, "$", "%", "#", and {create} semantics differ',
+    },
   },
   bufwinid = {
     args = 1,
@@ -873,6 +906,9 @@ M.funcs = {
     params = { { 'buf', 'any' } },
     returns = 'integer',
     signature = 'bufwinid({buf})',
+    see_lua = {
+      '|nvim_tabpage_list_wins()| with |nvim_win_get_buf()| after resolving {buf}; only the current tabpage is checked and no-match semantics differ',
+    },
   },
   bufwinnr = {
     args = 1,
@@ -893,6 +929,9 @@ M.funcs = {
     params = { { 'buf', 'any' } },
     returns = 'integer',
     signature = 'bufwinnr({buf})',
+    see_lua = {
+      '|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',
+    },
   },
   byte2line = {
     args = 1,
@@ -957,6 +996,9 @@ M.funcs = {
     params = { { 'expr', 'any' }, { 'nr', 'integer' }, { 'utf16', 'any' } },
     returns = 'integer',
     signature = 'byteidx({expr}, {nr} [, {utf16}])',
+    see_lua = {
+      '|vim.str_byteindex()| for string input with `"utf-32"` or `"utf-16"` and `strict_indexing = false`; composing characters and out-of-range semantics differ',
+    },
   },
   byteidxcomp = {
     args = { 2, 3 },
@@ -978,6 +1020,9 @@ M.funcs = {
     params = { { 'expr', 'any' }, { 'nr', 'integer' }, { 'utf16', 'any' } },
     returns = 'integer',
     signature = 'byteidxcomp({expr}, {nr} [, {utf16}])',
+    see_lua = {
+      '|vim.str_byteindex()| with `"utf-32"` or `"utf-16"` and `strict_indexing = false`',
+    },
   },
   call = {
     args = { 2, 3 },
@@ -997,6 +1042,7 @@ M.funcs = {
     returns = 'any',
     signature = 'call({func}, {arglist} [, {dict}])',
     tags = { 'E699' },
+    see_lua = false,
   },
   ceil = {
     args = 1,
@@ -1021,6 +1067,7 @@ M.funcs = {
     params = { { 'expr', 'number' } },
     returns = 'number',
     signature = 'ceil({expr})',
+    see_lua = { '|math.ceil()|' },
   },
   chanclose = {
     args = { 1, 2 },
@@ -1078,6 +1125,7 @@ M.funcs = {
     params = { { 'id', 'number' }, { 'data', 'string|string[]' } },
     returns = '0|1',
     signature = 'chansend({id}, {data})',
+    see_lua = { '|nvim_chan_send()| for string data; list input and the return value differ' },
   },
   char2nr = {
     args = { 1, 2 },
@@ -1103,6 +1151,7 @@ M.funcs = {
     params = { { 'string', 'string' }, { 'utf8', 'any' } },
     returns = '0|1',
     signature = 'char2nr({string} [, {utf8}])',
+    see_lua = { '|string.byte()|: only works with ASCII' },
   },
   charclass = {
     args = 1,
@@ -1141,6 +1190,9 @@ M.funcs = {
     params = { { 'expr', 'string|any[]' }, { 'winid', 'integer' } },
     returns = 'integer',
     signature = 'charcol({expr} [, {winid}])',
+    see_lua = {
+      '|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',
+    },
   },
   charidx = {
     args = { 2, 4 },
@@ -1188,6 +1240,9 @@ M.funcs = {
     },
     returns = 'integer',
     signature = 'charidx({string}, {idx} [, {countcc} [, {utf16}]])',
+    see_lua = {
+      '|vim.str_utfindex()| for string input with `"utf-32"` or `"utf-16"` and `strict_indexing = false`; `countcc = false` and out-of-range semantics differ',
+    },
   },
   chdir = {
     args = { 1, 2 },
@@ -1227,6 +1282,9 @@ M.funcs = {
     params = { { 'dir', 'string' }, { 'scope', 'string' } },
     returns = 'string',
     signature = 'chdir({dir} [, {scope}])',
+    see_lua = {
+      '|nvim_set_current_dir()| for the global directory; tab-local, window-local, and return semantics differ',
+    },
   },
   cindent = {
     args = 1,
@@ -1245,6 +1303,7 @@ M.funcs = {
     params = { { 'lnum', 'integer|string' } },
     returns = 'integer',
     signature = 'cindent({lnum})',
+    see_lua = false,
   },
   clearmatches = {
     args = { 0, 1 },
@@ -1335,6 +1394,9 @@ M.funcs = {
     params = { { 'expr', 'string|any[]' }, { 'winid', 'integer' } },
     returns = 'integer',
     signature = 'col({expr} [, {winid}])',
+    see_lua = {
+      '|nvim_win_get_cursor()| for "." (add 1), or Lua `#` on |nvim_get_current_line()| for "$"; marks, list input, and `virtualedit` differ',
+    },
   },
   complete = {
     args = 2,
@@ -1576,6 +1638,7 @@ M.funcs = {
     params = { { 'expr', 'T' } },
     returns = 'T',
     signature = 'copy({expr})',
+    see_lua = { '|vim.deepcopy()|; deeper than Vimscript |copy()|' },
   },
   cos = {
     args = 1,
@@ -1596,6 +1659,7 @@ M.funcs = {
     params = { { 'expr', 'number' } },
     returns = 'number',
     signature = 'cos({expr})',
+    see_lua = { '|math.cos()|' },
   },
   cosh = {
     args = 1,
@@ -1617,6 +1681,7 @@ M.funcs = {
     params = { { 'expr', 'number' } },
     returns = 'number',
     signature = 'cosh({expr})',
+    see_lua = { '|math.cosh()|' },
   },
   count = {
     args = { 2, 4 },
@@ -1707,6 +1772,7 @@ M.funcs = {
     name = 'cursor',
     params = { { 'lnum', 'integer|string' }, { 'col', 'integer' }, { 'off', 'integer' } },
     signature = 'cursor({lnum}, {col} [, {off}])',
+    see_lua = false, -- see cursor__1
   },
   cursor__1 = {
     args = { 1, 3 },
@@ -1747,6 +1813,9 @@ M.funcs = {
     name = 'cursor',
     params = { { 'list', 'integer[]' } },
     signature = 'cursor({list})',
+    see_lua = {
+      '|nvim_win_set_cursor()| with `{lnum, col - 1}`; `off`, `curswant`, and failure semantics differ',
+    },
   },
   debugbreak = {
     args = { 1, 1 },
@@ -1764,6 +1833,9 @@ M.funcs = {
     name = 'debugbreak',
     params = { { 'pid', 'integer' } },
     signature = 'debugbreak({pid})',
+    see_lua = {
+      '|uv.kill()| with `"sigtrap"` (or `"sigint"` outside MS-Windows); exact semantics differ',
+    },
   },
   deepcopy = {
     args = { 1, 2 },
@@ -1795,13 +1867,12 @@ M.funcs = {
     params = { { 'expr', 'T' }, { 'noref', 'boolean' } },
     returns = 'T',
     signature = 'deepcopy({expr} [, {noref}])',
+    see_lua = { '|vim.deepcopy()|' },
   },
   delete = {
     args = { 1, 2 },
     base = 1,
     desc = [=[
-      Lua: see |vim.fs.rm()|.
-
       Without {flags} or with {flags} empty: Deletes the file by the
       name {fname}.
 
@@ -1825,6 +1896,7 @@ M.funcs = {
     params = { { 'fname', 'string' }, { 'flags', 'string' } },
     returns = 'integer',
     signature = 'delete({fname} [, {flags}])',
+    see_lua = { '|vim.fs.rm()|' },
   },
   deletebufline = {
     args = { 2, 3 },
@@ -1851,6 +1923,7 @@ M.funcs = {
       { 'last', 'integer|string' },
     },
     signature = 'deletebufline({buf}, {first} [, {last}])',
+    see_lua = { '|nvim_buf_set_lines()|' },
   },
   dictwatcheradd = {
     args = 3,
@@ -1897,6 +1970,7 @@ M.funcs = {
     name = 'dictwatcheradd',
     params = { { 'dict', 'table' }, { 'pattern', 'string' }, { 'callback', 'function' } },
     signature = 'dictwatcheradd({dict}, {pattern}, {callback})',
+    see_lua = false,
   },
   dictwatcherdel = {
     args = 3,
@@ -1908,6 +1982,7 @@ M.funcs = {
     name = 'dictwatcherdel',
     params = { { 'dict', 'any' }, { 'pattern', 'string' }, { 'callback', 'function' } },
     signature = 'dictwatcherdel({dict}, {pattern}, {callback})',
+    see_lua = false,
   },
   did_filetype = {
     desc = [=[
@@ -2078,6 +2153,7 @@ M.funcs = {
     params = { { 'expr', 'any' } },
     returns = 'integer',
     signature = 'empty({expr})',
+    see_lua = { 'plain Lua emptiness checks, or |vim.tbl_isempty()| for tables' },
   },
   environ = {
     desc = [=[
@@ -2094,6 +2170,7 @@ M.funcs = {
     name = 'environ',
     params = {},
     signature = 'environ()',
+    see_lua = { '|uv.os_environ()| for the full environment table; |vim.env| for keyed access' },
   },
   escape = {
     args = 2,
@@ -2127,6 +2204,7 @@ M.funcs = {
     name = 'eval',
     params = { { 'string', 'string' } },
     signature = 'eval({string})',
+    see_lua = false,
   },
   eventhandler = {
     desc = [=[
@@ -2222,6 +2300,7 @@ M.funcs = {
     },
     returns = 'string',
     signature = 'execute({command} [, {silent}])',
+    see_lua = { '|nvim_exec()|', '|vim.cmd()|' },
   },
   exepath = {
     args = 1,
@@ -2356,6 +2435,7 @@ M.funcs = {
     name = 'exp',
     params = { { 'expr', 'number' } },
     signature = 'exp({expr})',
+    see_lua = { '|math.exp()|' },
   },
   expand = {
     args = { 1, 3 },
@@ -2547,6 +2627,9 @@ M.funcs = {
     name = 'extend',
     params = { { 'expr1', 'table' }, { 'expr2', 'table' }, { 'expr3', 'table' } },
     signature = 'extend({expr1}, {expr2} [, {expr3}])',
+    see_lua = {
+      '|vim.list_extend()| for lists, or |vim.tbl_extend()| and |vim.tbl_deep_extend()| for dicts; insertion and keep/force/error behavior differ',
+    },
   },
   extendnew = {
     args = { 2, 3 },
@@ -2559,6 +2642,9 @@ M.funcs = {
     name = 'extendnew',
     params = { { 'expr1', 'table' }, { 'expr2', 'table' }, { 'expr3', 'table' } },
     signature = 'extendnew({expr1}, {expr2} [, {expr3}])',
+    see_lua = {
+      '|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',
+    },
   },
   feedkeys = {
     args = { 1, 2 },
@@ -2613,6 +2699,7 @@ M.funcs = {
     name = 'feedkeys',
     params = { { 'string', 'string' }, { 'mode', 'string' } },
     signature = 'feedkeys({string} [, {mode}])',
+    see_lua = { '|nvim_feedkeys()|' },
   },
   file_readable = {
     args = 1,
@@ -2625,6 +2712,7 @@ M.funcs = {
     name = 'file_readable',
     params = { { 'file', 'string' } },
     signature = 'file_readable({file})',
+    see_lua = { '|uv.fs_access()| with `"R"` and |uv.fs_stat()| to exclude directories' },
   },
   filecopy = {
     args = 2,
@@ -2642,6 +2730,7 @@ M.funcs = {
     params = { { 'from', 'string' }, { 'to', 'string' } },
     returns = '0|1',
     signature = 'filecopy({from}, {to})',
+    see_lua = { '|uv.fs_copyfile()| with `{ excl = true }`; return semantics differ' },
   },
   filereadable = {
     args = 1,
@@ -2669,6 +2758,7 @@ M.funcs = {
     params = { { 'file', 'string' } },
     returns = '0|1',
     signature = 'filereadable({file})',
+    see_lua = { '|uv.fs_access()| with `"R"` and |uv.fs_stat()| to exclude directories' },
   },
   filewritable = {
     args = 1,
@@ -2685,6 +2775,9 @@ M.funcs = {
     params = { { 'file', 'string' } },
     returns = '0|1',
     signature = 'filewritable({file})',
+    see_lua = {
+      '|uv.fs_access()| with `"W"` and |uv.fs_stat()| if you need Vim\'s `2` return for directories',
+    },
   },
   filter = {
     args = 2,
@@ -2746,6 +2839,7 @@ M.funcs = {
     name = 'filter',
     params = { { 'expr1', 'string|table' }, { 'expr2', 'string|function' } },
     signature = 'filter({expr1}, {expr2})',
+    see_lua = { '|vim.tbl_filter()| for lists; dicts, strings, and blobs differ' },
   },
   finddir = {
     args = { 1, 3 },
@@ -2773,6 +2867,9 @@ M.funcs = {
     params = { { 'name', 'string' }, { 'path', 'string' }, { 'count', 'integer' } },
     returns = 'string|string[]',
     signature = 'finddir({name} [, {path} [, {count}]])',
+    see_lua = {
+      "|vim.fs.find()| with `type = 'directory'`; `path`, `count`, and return semantics differ",
+    },
   },
   findfile = {
     args = { 1, 3 },
@@ -2790,6 +2887,9 @@ M.funcs = {
     params = { { 'name', 'string' }, { 'path', 'string' }, { 'count', 'integer' } },
     returns = 'string|string[]',
     signature = 'findfile({name} [, {path} [, {count}]])',
+    see_lua = {
+      "|vim.fs.find()|; `path`, `count`, return semantics, and |'suffixesadd'| handling differ",
+    },
   },
   flatten = {
     args = { 1, 2 },
@@ -2818,6 +2918,9 @@ M.funcs = {
     params = { { 'list', 'any[]' }, { 'maxdepth', 'integer' } },
     returns = 'any[]|0',
     signature = 'flatten({list} [, {maxdepth}])',
+    see_lua = {
+      '`vim.iter(list):flatten():totable()` for a new flattened list; in-place updates and `maxdepth` differ',
+    },
   },
   flattennew = {
     args = { 1, 2 },
@@ -2829,6 +2932,9 @@ M.funcs = {
     params = { { 'list', 'any[]' }, { 'maxdepth', 'integer' } },
     returns = 'any[]|0',
     signature = 'flattennew({list} [, {maxdepth}])',
+    see_lua = {
+      '`vim.iter(list):flatten():totable()` for a new flattened list; `maxdepth` differs',
+    },
   },
   float2nr = {
     args = 1,
@@ -2859,6 +2965,7 @@ M.funcs = {
     name = 'float2nr',
     params = { { 'expr', 'number' } },
     signature = 'float2nr({expr})',
+    see_lua = { '|math.modf()| (first return value)' },
   },
   floor = {
     args = 1,
@@ -2881,6 +2988,7 @@ M.funcs = {
     name = 'floor',
     params = { { 'expr', 'number' } },
     signature = 'floor({expr})',
+    see_lua = { '|math.floor()|' },
   },
   fmod = {
     args = 2,
@@ -2905,6 +3013,7 @@ M.funcs = {
     name = 'fmod',
     params = { { 'expr1', 'number' }, { 'expr2', 'number' } },
     signature = 'fmod({expr1}, {expr2})',
+    see_lua = { '|math.fmod()|' },
   },
   fnameescape = {
     args = 1,
@@ -2932,6 +3041,9 @@ M.funcs = {
     params = { { 'string', 'string' } },
     returns = 'string',
     signature = 'fnameescape({string})',
+    see_lua = {
+      '|nvim_cmd()| or |vim.cmd()| with structured arguments to avoid Ex filename escaping',
+    },
   },
   fnamemodify = {
     args = 2,
@@ -2959,6 +3071,9 @@ M.funcs = {
     params = { { 'fname', 'string' }, { 'mods', 'string' } },
     returns = 'string',
     signature = 'fnamemodify({fname}, {mods})',
+    see_lua = {
+      '|vim.fs.dirname()|, |vim.fs.basename()|, |vim.fs.abspath()|, and |vim.fs.normalize()| for common path modifiers; modifier coverage differs',
+    },
   },
   foldclosed = {
     args = 1,
@@ -3096,6 +3211,7 @@ M.funcs = {
     params = { { 'expr1', 'string|table' }, { 'expr2', 'string|function' } },
     returns = 'string|table',
     signature = 'foreach({expr1}, {expr2})',
+    see_lua = { '|pairs()|', '|ipairs()|' },
   },
   foreground = {
     args = 0,
@@ -3142,6 +3258,7 @@ M.funcs = {
     name = 'funcref',
     params = { { 'name', 'string' }, { 'arglist', 'any' }, { 'dict', 'any' } },
     signature = 'funcref({name} [, {arglist}] [, {dict}])',
+    see_lua = false,
   },
   ['function'] = {
     args = { 1, 3 },
@@ -3233,6 +3350,7 @@ M.funcs = {
     params = { { 'name', 'string' }, { 'arglist', 'any' }, { 'dict', 'any' } },
     signature = 'function({name} [, {arglist}] [, {dict}])',
     tags = { 'partial', 'E700', 'E923' },
+    see_lua = false,
   },
   garbagecollect = {
     args = { 0, 1 },
@@ -3259,6 +3377,7 @@ M.funcs = {
     name = 'garbagecollect',
     params = { { 'atexit', 'boolean' } },
     signature = 'garbagecollect([{atexit}])',
+    see_lua = false,
   },
   get = {
     args = { 2, 3 },
@@ -3272,6 +3391,7 @@ M.funcs = {
     params = { { 'list', 'any[]' }, { 'idx', 'integer' }, { 'default', 'any' } },
     signature = 'get({list}, {idx} [, {default}])',
     tags = { 'get()-list' },
+    see_lua = false,
   },
   get__1 = {
     args = { 2, 3 },
@@ -3285,6 +3405,7 @@ M.funcs = {
     params = { { 'blob', 'string' }, { 'idx', 'integer' }, { 'default', 'any' } },
     signature = 'get({blob}, {idx} [, {default}])',
     tags = { 'get()-blob' },
+    see_lua = false,
   },
   get__2 = {
     args = { 2, 3 },
@@ -3301,6 +3422,7 @@ M.funcs = {
     params = { { 'dict', 'table<string,any>' }, { 'key', 'string' }, { 'default', 'any' } },
     signature = 'get({dict}, {key} [, {default}])',
     tags = { 'get()-dict' },
+    see_lua = false,
   },
   get__3 = {
     args = { 2, 3 },
@@ -3332,6 +3454,7 @@ M.funcs = {
     returns = 'any',
     signature = 'get({func}, {what})',
     tags = { 'get()-func' },
+    see_lua = false,
   },
   getbufinfo = {
     args = { 0, 1 },
@@ -3451,6 +3574,7 @@ M.funcs = {
     params = { { 'buf', 'integer|string' }, { 'lnum', 'integer' }, { 'end', 'integer' } },
     returns = 'string[]',
     signature = 'getbufline({buf}, {lnum} [, {end}])',
+    see_lua = { '|nvim_buf_get_lines()|' },
   },
   getbufoneline = {
     args = 2,
@@ -3463,6 +3587,7 @@ M.funcs = {
     params = { { 'buf', 'integer|string' }, { 'lnum', 'integer' } },
     signature = 'getbufoneline({buf}, {lnum})',
     returns = 'string',
+    see_lua = { '|nvim_buf_get_lines()|' },
   },
   getbufvar = {
     args = { 2, 3 },
@@ -3492,6 +3617,9 @@ M.funcs = {
     name = 'getbufvar',
     params = { { 'buf', 'integer|string' }, { 'varname', 'string' }, { 'def', 'any' } },
     signature = 'getbufvar({buf}, {varname} [, {def}])',
+    see_lua = {
+      '|nvim_buf_get_var()| or |vim.b| after resolving {buf} to a bufnr; option names use |nvim_get_option_value()| or |vim.bo|',
+    },
   },
   getcellwidths = {
     desc = [=[
@@ -3966,6 +4094,9 @@ M.funcs = {
     params = { { 'winid', 'integer' } },
     returns = '[integer, integer, integer, integer, integer]',
     signature = 'getcurpos([{winid}])',
+    see_lua = {
+      '|nvim_win_get_cursor()|; return shape, 0-based column, and `curswant`/invalid-window semantics differ',
+    },
   },
   getcursorcharpos = {
     args = { 0, 1 },
@@ -4011,6 +4142,9 @@ M.funcs = {
     params = { { 'winnr', 'integer' }, { 'tabnr', 'integer' } },
     returns = 'string',
     signature = 'getcwd([{winnr} [, {tabnr}]])',
+    see_lua = {
+      '|uv.cwd()| for the global working directory; tab-local and window-local scopes differ',
+    },
   },
   getenv = {
     args = 1,
@@ -4029,6 +4163,7 @@ M.funcs = {
     params = { { 'name', 'string' } },
     returns = 'string',
     signature = 'getenv({name})',
+    see_lua = { '|vim.env|' },
   },
   getfontname = {
     args = { 0, 1 },
@@ -4073,6 +4208,7 @@ M.funcs = {
     params = { { 'fname', 'string' } },
     returns = 'string',
     signature = 'getfperm({fname})',
+    see_lua = { '|uv.fs_stat()|' },
   },
   getfsize = {
     args = 1,
@@ -4090,6 +4226,7 @@ M.funcs = {
     params = { { 'fname', 'string' } },
     returns = 'integer',
     signature = 'getfsize({fname})',
+    see_lua = { '|uv.fs_stat()|' },
   },
   getftime = {
     args = 1,
@@ -4107,6 +4244,7 @@ M.funcs = {
     params = { { 'fname', 'string' } },
     returns = 'integer',
     signature = 'getftime({fname})',
+    see_lua = { '|uv.fs_stat()|' },
   },
   getftype = {
     args = 1,
@@ -4137,6 +4275,7 @@ M.funcs = {
     params = { { 'fname', 'string' } },
     returns = "'file'|'dir'|'link'|'bdev'|'cdev'|'socket'|'fifo'|'other'",
     signature = 'getftype({fname})',
+    see_lua = { '|uv.fs_stat()|' },
   },
   getjumplist = {
     args = { 0, 2 },
@@ -4166,6 +4305,9 @@ M.funcs = {
     params = { { 'winnr', 'integer' }, { 'tabnr', 'integer' } },
     signature = 'getjumplist([{winnr} [, {tabnr}]])',
     returns = 'vim.fn.getjumplist.ret',
+    see_lua = {
+      '|nvim_get_context()| for current jump history; window/tab arguments and return shape differ',
+    },
   },
   getline = {
     args = { 1, 2 },
@@ -4199,6 +4341,7 @@ M.funcs = {
     params = { { 'lnum', 'integer|string' }, { 'end', 'nil|false' } },
     signature = 'getline({lnum} [, {end}])',
     returns = 'string',
+    see_lua = { '|nvim_get_current_line()|', '|nvim_buf_get_lines()|' },
   },
   getline__1 = {
     args = { 2 },
@@ -4206,6 +4349,7 @@ M.funcs = {
     name = 'getline',
     params = { { 'lnum', 'integer|string' }, { 'end', 'true|number|string|table' } },
     returns = 'string|string[]',
+    see_lua = { '|nvim_get_current_line()|', '|nvim_buf_get_lines()|' },
   },
   getloclist = {
     args = { 1, 2 },
@@ -4359,6 +4503,7 @@ M.funcs = {
     params = {},
     returns = 'integer',
     signature = 'getpid()',
+    see_lua = { '|uv.os_getpid()|' },
   },
   getpos = {
     args = 1,
@@ -4429,6 +4574,9 @@ M.funcs = {
     params = { { 'expr', 'string' } },
     returns = '[integer, integer, integer, integer]',
     signature = 'getpos({expr})',
+    see_lua = {
+      '|nvim_win_get_cursor()| for "." or |nvim_buf_get_mark()| for marks; return shape, `off`, and special-position semantics differ',
+    },
   },
   getqflist = {
     args = { 0, 1 },
@@ -4812,6 +4960,7 @@ M.funcs = {
     params = {},
     returns = 'table[]',
     signature = 'getstacktrace()',
+    see_lua = { '|debug.traceback()|' },
   },
   gettabinfo = {
     args = { 0, 1 },
@@ -4851,6 +5000,7 @@ M.funcs = {
     name = 'gettabvar',
     params = { { 'tabnr', 'integer' }, { 'varname', 'string' }, { 'def', 'any' } },
     signature = 'gettabvar({tabnr}, {varname} [, {def}])',
+    see_lua = { '|nvim_tabpage_get_var()|', '|vim.t|' },
   },
   gettabwinvar = {
     args = { 3, 4 },
@@ -4890,6 +5040,9 @@ M.funcs = {
       { 'def', 'any' },
     },
     signature = 'gettabwinvar({tabnr}, {winnr}, {varname} [, {def}])',
+    see_lua = {
+      '|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|',
+    },
   },
   gettagstack = {
     args = { 0, 1 },
@@ -5056,6 +5209,9 @@ M.funcs = {
     name = 'getwinvar',
     params = { { 'winnr', 'integer' }, { 'varname', 'string' }, { 'def', 'any' } },
     signature = 'getwinvar({winnr}, {varname} [, {def}])',
+    see_lua = {
+      '|nvim_win_get_var()| or |vim.w| after resolving {winnr}; option names use |nvim_get_option_value()| or |vim.wo|',
+    },
   },
   glob = {
     args = { 1, 4 },
@@ -5272,6 +5428,7 @@ M.funcs = {
     params = { { 'dict', 'table' }, { 'key', 'string' } },
     returns = '0|1',
     signature = 'has_key({dict}, {key})',
+    see_lua = { '`dict[key] ~= nil`' },
   },
   haslocaldir = {
     args = { 0, 2 },
@@ -5349,6 +5506,7 @@ M.funcs = {
     func = 'f_hlID',
     params = { { 'name', 'string' } },
     signature = 'highlightID({name})',
+    see_lua = { '|nvim_get_hl()|' },
   },
   highlight_exists = {
     args = 1,
@@ -5360,6 +5518,7 @@ M.funcs = {
     func = 'f_hlexists',
     params = { { 'name', 'string' } },
     signature = 'highlight_exists({name})',
+    see_lua = { '|nvim_get_hl()|' },
   },
   histadd = {
     args = 2,
@@ -5491,6 +5650,7 @@ M.funcs = {
     params = { { 'name', 'string' } },
     returns = 'integer',
     signature = 'hlID({name})',
+    see_lua = { '|nvim_get_hl()|' },
   },
   hlexists = {
     args = 1,
@@ -5506,6 +5666,7 @@ M.funcs = {
     params = { { 'name', 'string' } },
     returns = '0|1',
     signature = 'hlexists({name})',
+    see_lua = { '|nvim_get_hl()|' },
   },
   hostname = {
     desc = [=[
@@ -5518,6 +5679,7 @@ M.funcs = {
     params = {},
     returns = 'string',
     signature = 'hostname()',
+    see_lua = { '|uv.os_gethostname()|' },
   },
   iconv = {
     args = 3,
@@ -5540,6 +5702,7 @@ M.funcs = {
     params = { { 'string', 'string' }, { 'from', 'string' }, { 'to', 'string' } },
     returns = 'string',
     signature = 'iconv({string}, {from}, {to})',
+    see_lua = { '|vim.iconv()|' },
   },
   id = {
     args = 1,
@@ -5564,6 +5727,7 @@ M.funcs = {
     params = { { 'expr', 'any' } },
     returns = 'string',
     signature = 'id({expr})',
+    see_lua = false,
   },
   indent = {
     args = 1,
@@ -5619,6 +5783,9 @@ M.funcs = {
     params = { { 'object', 'any' }, { 'expr', 'any' }, { 'start', 'integer' }, { 'ic', 'boolean' } },
     returns = 'integer',
     signature = 'index({object}, {expr} [, {start} [, {ic}]])',
+    see_lua = {
+      '|vim.iter()| with |Iter:enumerate()| and |Iter:find()| for lists; result is 1-based, and `start`, `ic`, and Blob semantics differ',
+    },
   },
   indexof = {
     args = { 2, 3 },
@@ -5667,6 +5834,9 @@ M.funcs = {
     params = { { 'object', 'any' }, { 'expr', 'any' }, { 'opts', 'table' } },
     returns = 'integer',
     signature = 'indexof({object}, {expr} [, {opts}])',
+    see_lua = {
+      '|vim.iter()| with |Iter:enumerate()| and |Iter:find()| for list predicates; result is 1-based, and `startidx` and Blob semantics differ',
+    },
   },
   input = {
     args = { 1, 3 },
@@ -5676,6 +5846,7 @@ M.funcs = {
     params = { { 'prompt', 'string' }, { 'text', 'string' }, { 'completion', 'string' } },
     returns = 'string',
     signature = 'input({prompt} [, {text} [, {completion}]])',
+    see_lua = { '|vim.ui.input()| for callback-based input' },
   },
   input__1 = {
     args = { 1, 3 },
@@ -5796,6 +5967,7 @@ M.funcs = {
     params = { { 'opts', 'table' } },
     returns = 'string',
     signature = 'input({opts})',
+    see_lua = { '|vim.ui.input()| for callback-based input' },
   },
   inputdialog = {
     args = { 1, 3 },
@@ -5806,6 +5978,7 @@ M.funcs = {
     ]=],
     params = VARARGS,
     signature = 'input(...)',
+    see_lua = { '|vim.ui.input()| for callback-based input' },
   },
   inputlist = {
     args = 1,
@@ -5831,6 +6004,9 @@ M.funcs = {
     name = 'inputlist',
     params = { { 'textlist', 'string[]' } },
     signature = 'inputlist({textlist})',
+    see_lua = {
+      '|vim.ui.select()| for simple selection menus; callback, returned item, and out-of-range semantics differ',
+    },
   },
   inputrestore = {
     desc = [=[
@@ -5903,6 +6079,7 @@ M.funcs = {
     name = 'insert',
     params = { { 'object', 'any' }, { 'item', 'any' }, { 'idx', 'integer' } },
     signature = 'insert({object}, {item} [, {idx}])',
+    see_lua = { '|table.insert()| for lists; blob insertion and negative indexes differ' },
   },
   interrupt = {
     args = 0,
@@ -5923,6 +6100,7 @@ M.funcs = {
     name = 'interrupt',
     params = {},
     signature = 'interrupt()',
+    see_lua = false,
   },
   invert = {
     args = 1,
@@ -5937,6 +6115,7 @@ M.funcs = {
     params = { { 'expr', 'integer' } },
     returns = 'integer',
     signature = 'invert({expr})',
+    see_lua = { '|bit.bnot()|' },
   },
   isabsolutepath = {
     args = 1,
@@ -5977,6 +6156,7 @@ M.funcs = {
     params = { { 'directory', 'string' } },
     returns = '0|1',
     signature = 'isdirectory({directory})',
+    see_lua = { '|uv.fs_stat()| and check `type == "directory"`' },
   },
   isinf = {
     args = 1,
@@ -5994,6 +6174,7 @@ M.funcs = {
     params = { { 'expr', 'number' } },
     returns = '1|0|-1',
     signature = 'isinf({expr})',
+    see_lua = { '`expr == math.huge and 1 or expr == -math.huge and -1 or 0`' },
   },
   islocked = {
     args = 1,
@@ -6018,6 +6199,7 @@ M.funcs = {
     returns = '0|1',
     signature = 'islocked({expr})',
     tags = { 'E786' },
+    see_lua = false,
   },
   isnan = {
     args = 1,
@@ -6032,6 +6214,7 @@ M.funcs = {
     params = { { 'expr', 'number' } },
     returns = '0|1',
     signature = 'isnan({expr})',
+    see_lua = { '`expr ~= expr`' },
   },
   items = {
     args = 1,
@@ -6059,6 +6242,7 @@ M.funcs = {
     name = 'items',
     params = { { 'expr', 'table|string' } },
     signature = 'items({expr})',
+    see_lua = { '|pairs()|', '|ipairs()|' },
   },
   jobclose = {
     args = { 1, 2 },
@@ -6079,6 +6263,7 @@ M.funcs = {
     params = { { 'job', 'integer' } },
     returns = 'integer',
     signature = 'jobpid({job})',
+    see_lua = { '|vim.system()| object `.pid`; |job-id| and channel semantics differ' },
   },
   jobresize = {
     args = 3,
@@ -6100,12 +6285,11 @@ M.funcs = {
     func = 'f_chansend',
     params = VARARGS,