Merge remote-tracking branch 'upstream/master' into mix_20240309HEADrahm

1 files changed, 186 insertions, 51 deletions

diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index a418b34909..9d787c68ea 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -17,6 +17,7 @@
 --- @field deprecated? true
 --- @field returns? string|false
 --- @field returns_desc? string
+--- @field generics? string[] Used to write `---@generic` annotations over a function.
 --- @field signature? string
 --- @field desc? string
 --- @field params [string, string, string][]
@@ -1383,16 +1384,22 @@ M.funcs = {
       		See |complete_info_mode| for the values.
          pum_visible	|TRUE| if popup menu is visible.
       		See |pumvisible()|.
-         items	List of completion matches.  Each item is a
-      		dictionary containing the entries "word",
+         items	List of all completion candidates.  Each item
+      		is a dictionary containing the entries "word",
       		"abbr", "menu", "kind", "info" and "user_data".
       		See |complete-items|.
+         matches	Same as "items", but only returns items that
+      		are matching current query. If both "matches"
+      		and "items" are in "what", the returned list
+      		will still be named "items", but each item
+      		will have an additional "match" field.
          selected	Selected item index.  First index is zero.
       		Index is -1 if no item is selected (showing
       		typed text only, or the last completion after
       		no item is selected when using the <Up> or
       		<Down> keys)
-         inserted	Inserted string. [NOT IMPLEMENTED YET]
+         completed	Return a dictionary containing the entries of
+      		the currently selected index item.
          preview_winid     Info floating preview window id.
          preview_bufnr     Info floating preview buffer id.
 
@@ -1521,9 +1528,10 @@ M.funcs = {
       A |Dictionary| is copied in a similar way as a |List|.
       Also see |deepcopy()|.
     ]=],
+    generics = { 'T' },
     name = 'copy',
-    params = { { 'expr', 'any' } },
-    returns = 'any',
+    params = { { 'expr', 'T' } },
+    returns = 'T',
     signature = 'copy({expr})',
   },
   cos = {
@@ -1639,6 +1647,7 @@ M.funcs = {
     ]=],
     name = 'ctxset',
     params = { { 'context', 'table' }, { 'index', 'integer' } },
+    returns = 'integer',
     signature = 'ctxset({context} [, {index}])',
   },
   ctxsize = {
@@ -1738,8 +1747,10 @@ M.funcs = {
       Also see |copy()|.
 
     ]=],
+    generics = { 'T' },
     name = 'deepcopy',
-    params = { { 'expr', 'any' }, { 'noref', 'boolean' } },
+    params = { { 'expr', 'T' }, { 'noref', 'boolean' } },
+    returns = 'T',
     signature = 'deepcopy({expr} [, {noref}])',
   },
   delete = {
@@ -1869,6 +1880,7 @@ M.funcs = {
     fast = true,
     name = 'did_filetype',
     params = {},
+    returns = 'integer',
     signature = 'did_filetype()',
   },
   diff_filler = {
@@ -1886,6 +1898,7 @@ M.funcs = {
     ]=],
     name = 'diff_filler',
     params = { { 'lnum', 'integer' } },
+    returns = 'integer',
     signature = 'diff_filler({lnum})',
   },
   diff_hlID = {
@@ -1930,6 +1943,7 @@ M.funcs = {
     ]=],
     name = 'digraph_get',
     params = { { 'chars', 'string' } },
+    returns = 'string',
     signature = 'digraph_get({chars})',
   },
   digraph_getlist = {
@@ -1952,6 +1966,7 @@ M.funcs = {
     ]=],
     name = 'digraph_getlist',
     params = { { 'listall', 'boolean' } },
+    returns = 'string[][]',
     signature = 'digraph_getlist([{listall}])',
   },
   digraph_set = {
@@ -2016,6 +2031,7 @@ M.funcs = {
     ]=],
     name = 'empty',
     params = { { 'expr', 'any' } },
+    returns = 'integer',
     signature = 'empty({expr})',
   },
   environ = {
@@ -2048,6 +2064,7 @@ M.funcs = {
     fast = true,
     name = 'escape',
     params = { { 'string', 'string' }, { 'chars', 'string' } },
+    returns = 'string',
     signature = 'escape({string}, {chars})',
   },
   eval = {
@@ -3018,6 +3035,7 @@ M.funcs = {
     ]=],
     name = 'foreach',
     params = { { 'expr1', 'string|table' }, { 'expr2', 'string|function' } },
+    returns = 'string|table',
     signature = 'foreach({expr1}, {expr2})',
   },
   foreground = {
@@ -3372,6 +3390,7 @@ M.funcs = {
     ]=],
     name = 'getbufline',
     params = { { 'buf', 'integer|string' }, { 'lnum', 'integer' }, { 'end', 'integer' } },
+    returns = 'string[]',
     signature = 'getbufline({buf}, {lnum} [, {end}])',
   },
   getbufoneline = {
@@ -3452,15 +3471,17 @@ M.funcs = {
     signature = 'getchangelist([{buf}])',
   },
   getchar = {
-    args = { 0, 1 },
+    args = { 0, 2 },
     desc = [=[
       Get a single character from the user or input stream.
-      If {expr} is omitted, wait until a character is available.
+      If {expr} is omitted or is -1, wait until a character is
+      	available.
       If {expr} is 0, only get a character when one is available.
       	Return zero otherwise.
       If {expr} is 1, only check if a character is available, it is
       	not consumed.  Return zero if no character available.
-      If you prefer always getting a string use |getcharstr()|.
+      If you prefer always getting a string use |getcharstr()|, or
+      specify |FALSE| as "number" in {opts}.
 
       Without {expr} and when {expr} is 0 a whole character or
       special key is returned.  If it is a single character, the
@@ -3470,7 +3491,8 @@ M.funcs = {
       starting with 0x80 (decimal: 128).  This is the same value as
       the String "\<Key>", e.g., "\<Left>".  The returned value is
       also a String when a modifier (shift, control, alt) was used
-      that is not included in the character.
+      that is not included in the character.  |keytrans()| can also
+      be used to convert a returned String into a readable form.
 
       When {expr} is 0 and Esc is typed, there will be a short delay
       while Vim waits to see if this is the start of an escape
@@ -3482,6 +3504,32 @@ M.funcs = {
 
       Use getcharmod() to obtain any additional modifiers.
 
+      The optional argument {opts} is a Dict and supports the
+      following items:
+
+      	cursor		A String specifying cursor behavior
+      			when waiting for a character.
+      			"hide": hide the cursor.
+      			"keep": keep current cursor unchanged.
+      			"msg": move cursor to message area.
+      			(default: automagically decide
+      			between "keep" and "msg")
+
+      	number		If |TRUE|, return a Number when getting
+      			a single character.
+      			If |FALSE|, the return value is always
+      			converted to a String, and an empty
+      			String (instead of 0) is returned when
+      			no character is available.
+      			(default: |TRUE|)
+
+      	simplify	If |TRUE|, include modifiers in the
+      			character if possible.  E.g., return
+      			the same value for CTRL-I and <Tab>.
+      			If |FALSE|, don't include modifiers in
+      			the character.
+      			(default: |TRUE|)
+
       When the user clicks a mouse button, the mouse event will be
       returned.  The position can then be found in |v:mouse_col|,
       |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|.
@@ -3519,9 +3567,9 @@ M.funcs = {
       <
     ]=],
     name = 'getchar',
-    params = { { 'expr', '0|1' } },
-    returns = 'integer',
-    signature = 'getchar([{expr}])',
+    params = { { 'expr', '-1|0|1' }, { 'opts', 'table' } },
+    returns = 'integer|string',
+    signature = 'getchar([{expr} [, {opts}]])',
   },
   getcharmod = {
     desc = [=[
@@ -3594,21 +3642,13 @@ M.funcs = {
     signature = 'getcharsearch()',
   },
   getcharstr = {
-    args = { 0, 1 },
+    args = { 0, 2 },
     desc = [=[
-      Get a single character from the user or input stream as a
-      string.
-      If {expr} is omitted, wait until a character is available.
-      If {expr} is 0 or false, only get a character when one is
-      	available.  Return an empty string otherwise.
-      If {expr} is 1 or true, only check if a character is
-      	available, it is not consumed.  Return an empty string
-      	if no character is available.
-      Otherwise this works like |getchar()|, except that a number
-      result is converted to a string.
+      The same as |getchar()|, except that this always returns a
+      String, and "number" isn't allowed in {opts}.
     ]=],
     name = 'getcharstr',
-    params = { { 'expr', '0|1' } },
+    params = { { 'expr', '-1|0|1' }, { 'opts', 'table' } },
     returns = 'string',
     signature = 'getcharstr([{expr}])',
   },
@@ -3700,6 +3740,7 @@ M.funcs = {
     ]=],
     name = 'getcmdscreenpos',
     params = {},
+    returns = 'integer',
     signature = 'getcmdscreenpos()',
   },
   getcmdtype = {
@@ -4651,6 +4692,25 @@ M.funcs = {
     returns = 'vim.fn.getscriptinfo.ret[]',
     signature = 'getscriptinfo([{opts}])',
   },
+  getstacktrace = {
+    args = 0,
+    desc = [=[
+      Returns the current stack trace of Vim scripts.
+      Stack trace is a |List|, of which each item is a |Dictionary|
+      with the following items:
+          funcref	The funcref if the stack is at a function,
+      		otherwise this item is omitted.
+          event	The string of the event description if the
+      		stack is at an autocmd event, otherwise this
+      		item is omitted.
+          lnum	The line number in the script on the stack.
+          filepath	The file path of the script on the stack.
+    ]=],
+    name = 'getstacktrace',
+    params = {},
+    returns = 'table[]',
+    signature = 'getstacktrace()',
+  },
   gettabinfo = {
     args = { 0, 1 },
     base = 1,
@@ -4781,6 +4841,7 @@ M.funcs = {
     ]=],
     name = 'gettext',
     params = { { 'text', 'string' } },
+    returns = 'string',
     signature = 'gettext({text})',
   },
   getwininfo = {
@@ -4800,6 +4861,8 @@ M.funcs = {
       	botline		last complete displayed buffer line
       	bufnr		number of buffer in the window
       	height		window height (excluding winbar)
+      	leftcol		first column displayed; only used when
+      			'wrap' is off
       	loclist		1 if showing a location list
       	quickfix	1 if quickfix or location list window
       	terminal	1 if a terminal window
@@ -4963,6 +5026,7 @@ M.funcs = {
     ]=],
     name = 'glob2regpat',
     params = { { 'string', 'string' } },
+    returns = 'string',
     signature = 'glob2regpat({string})',
   },
   globpath = {
@@ -5370,6 +5434,7 @@ M.funcs = {
     fast = true,
     name = 'iconv',
     params = { { 'string', 'string' }, { 'from', 'string' }, { 'to', 'string' } },
+    returns = 'string',
     signature = 'iconv({string}, {from}, {to})',
   },
   id = {
@@ -5393,6 +5458,7 @@ M.funcs = {
     ]=],
     name = 'id',
     params = { { 'expr', 'any' } },
+    returns = 'string',
     signature = 'id({expr})',
   },
   indent = {
@@ -5445,6 +5511,7 @@ M.funcs = {
     ]=],
     name = 'index',
     params = { { 'object', 'any' }, { 'expr', 'any' }, { 'start', 'integer' }, { 'ic', 'boolean' } },
+    returns = 'integer',
     signature = 'index({object}, {expr} [, {start} [, {ic}]])',
   },
   indexof = {
@@ -5492,6 +5559,7 @@ M.funcs = {
     ]=],
     name = 'indexof',
     params = { { 'object', 'any' }, { 'expr', 'any' }, { 'opts', 'table' } },
+    returns = 'integer',
     signature = 'indexof({object}, {expr} [, {opts}])',
   },
   input = {
@@ -5500,6 +5568,7 @@ M.funcs = {
     desc = '',
     name = 'input',
     params = { { 'prompt', 'string' }, { 'text', 'string' }, { 'completion', 'string' } },
+    returns = 'string',
     signature = 'input({prompt} [, {text} [, {completion}]])',
   },
   input__1 = {
@@ -5619,6 +5688,7 @@ M.funcs = {
     ]=],
     name = 'input',
     params = { { 'opts', 'table' } },
+    returns = 'string',
     signature = 'input({opts})',
   },
   inputdialog = {
@@ -5665,6 +5735,7 @@ M.funcs = {
     ]=],
     name = 'inputrestore',
     params = {},
+    returns = 'integer',
     signature = 'inputrestore()',
   },
   inputsave = {
@@ -5678,6 +5749,7 @@ M.funcs = {
     ]=],
     name = 'inputsave',
     params = {},
+    returns = 'integer',
     signature = 'inputsave()',
   },
   inputsecret = {
@@ -5697,6 +5769,7 @@ M.funcs = {
     ]=],
     name = 'inputsecret',
     params = { { 'prompt', 'string' }, { 'text', 'string' } },
+    returns = 'string',
     signature = 'inputsecret({prompt} [, {text}])',
   },
   insert = {
@@ -5754,7 +5827,8 @@ M.funcs = {
       <
     ]=],
     name = 'invert',
-    params = { { 'expr', 'number' } },
+    params = { { 'expr', 'integer' } },
+    returns = 'integer',
     signature = 'invert({expr})',
   },
   isabsolutepath = {
@@ -5870,7 +5944,7 @@ M.funcs = {
       the index.
     ]=],
     name = 'items',
-    params = { { 'dict', 'any' } },
+    params = { { 'dict', 'table' } },
     signature = 'items({dict})',
   },
   jobclose = {
@@ -5917,7 +5991,7 @@ M.funcs = {
   jobstart = {
     args = { 1, 2 },
     desc = [=[
-      Note: Prefer |vim.system()| in Lua (unless using the `pty` option).
+      Note: Prefer |vim.system()| in Lua (unless using `rpc`, `pty`, or `term`).
 
       Spawns {cmd} as a job.
       If {cmd} is a List it runs directly (no 'shell').
@@ -5925,8 +5999,11 @@ M.funcs = {
         call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}'])
       <(See |shell-unquoting| for details.)
 
-      Example: >vim
-        call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}})
+      Example: start a job and handle its output: >vim
+        call jobstart(['nvim', '-h'], {'on_stdout':{j,d,e->append(line('.'),d)}})
+      <
+      Example: start a job in a |terminal| connected to the current buffer: >vim
+        call jobstart(['nvim', '-h'], {'term':v:true})
       <
       Returns |job-id| on success, 0 on invalid arguments (or job
       table is full), -1 if {cmd}[0] or 'shell' is not executable.
@@ -5991,6 +6068,10 @@ M.funcs = {
         stdin:      (string) Either "pipe" (default) to connect the
       	      job's stdin to a channel or "null" to disconnect
       	      stdin.
+        term:	    (boolean) Spawns {cmd} in a new pseudo-terminal session
+                connected to the current (unmodified) buffer. Implies "pty".
+                Default "height" and "width" are set to the current window
+                dimensions. |jobstart()|. Defaults $TERM to "xterm-256color".
         width:      (number) Width of the `pty` terminal.
 
       {opts} is passed as |self| dictionary to the callback; the
@@ -6004,6 +6085,7 @@ M.funcs = {
     ]=],
     name = 'jobstart',
     params = { { 'cmd', 'string|string[]' }, { 'opts', 'table' } },
+    returns = 'integer',
     signature = 'jobstart({cmd} [, {opts}])',
   },
   jobstop = {
@@ -6020,6 +6102,7 @@ M.funcs = {
     ]=],
     name = 'jobstop',
     params = { { 'id', 'integer' } },
+    returns = 'integer',
     signature = 'jobstop({id})',
   },
   jobwait = {
@@ -6047,6 +6130,7 @@ M.funcs = {
     ]=],
     name = 'jobwait',
     params = { { 'jobs', 'integer[]' }, { 'timeout', 'integer' } },
+    returns = 'integer[]',
     signature = 'jobwait({jobs} [, {timeout}])',
   },
   join = {
@@ -6066,6 +6150,7 @@ M.funcs = {
     ]=],
     name = 'join',
     params = { { 'list', 'any[]' }, { 'sep', 'string' } },
+    returns = 'string',
     signature = 'join({list} [, {sep}])',
   },
   json_decode = {
@@ -6109,6 +6194,7 @@ M.funcs = {
     ]=],
     name = 'json_encode',
     params = { { 'expr', 'any' } },
+    returns = 'string',
     signature = 'json_encode({expr})',
   },
   keys = {
@@ -6121,6 +6207,7 @@ M.funcs = {
     ]=],
     name = 'keys',
     params = { { 'dict', 'table' } },
+    returns = 'string[]',
     signature = 'keys({dict})',
   },
   keytrans = {
@@ -6136,6 +6223,7 @@ M.funcs = {
     ]=],
     name = 'keytrans',
     params = { { 'string', 'string' } },
+    returns = 'string',
     signature = 'keytrans({string})',
   },
   last_buffer_nr = {
@@ -6162,7 +6250,8 @@ M.funcs = {
 
     ]=],
     name = 'len',
-    params = { { 'expr', 'any' } },
+    params = { { 'expr', 'any[]' } },
+    returns = 'integer',
     signature = 'len({expr})',
     tags = { 'E701' },
   },
@@ -6297,6 +6386,7 @@ M.funcs = {
     ]=],
     name = 'lispindent',
     params = { { 'lnum', 'integer' } },
+    returns = 'integer',
     signature = 'lispindent({lnum})',
   },
   list2blob = {
@@ -6315,6 +6405,7 @@ M.funcs = {
     ]=],
     name = 'list2blob',
     params = { { 'list', 'any[]' } },
+    returns = 'string',
     signature = 'list2blob({list})',
   },
   list2str = {
@@ -6339,6 +6430,7 @@ M.funcs = {
     ]=],
     name = 'list2str',
     params = { { 'list', 'any[]' }, { 'utf8', 'boolean' } },
+    returns = 'string',
     signature = 'list2str({list} [, {utf8}])',
   },
   localtime = {
@@ -6348,6 +6440,7 @@ M.funcs = {
     ]=],
     name = 'localtime',
     params = {},
+    returns = 'integer',
     signature = 'localtime()',
   },
   log = {
@@ -6368,6 +6461,7 @@ M.funcs = {
     float_func = 'log',
     name = 'log',
     params = { { 'expr', 'number' } },
+    returns = 'number',
     signature = 'log({expr})',
   },
   log10 = {
@@ -6387,6 +6481,7 @@ M.funcs = {
     float_func = 'log10',
     name = 'log10',
     params = { { 'expr', 'number' } },
+    returns = 'number',
     signature = 'log10({expr})',
   },
   luaeval = {
@@ -7271,6 +7366,7 @@ M.funcs = {
     ]=],
     name = 'max',
     params = { { 'expr', 'any' } },
+    returns = 'number',
     signature = 'max({expr})',
   },
   menu_get = {
@@ -7419,6 +7515,7 @@ M.funcs = {
     ]=],
     name = 'min',
     params = { { 'expr', 'any' } },
+    returns = 'number',
     signature = 'min({expr})',
   },
   mkdir = {
@@ -7467,6 +7564,7 @@ M.funcs = {
     ]=],
     name = 'mkdir',
     params = { { 'name', 'string' }, { 'flags', 'string' }, { 'prot', 'string' } },
+    returns = 'integer',
     signature = 'mkdir({name} [, {flags} [, {prot}]])',
     tags = { 'E739' },
   },
@@ -7646,6 +7744,7 @@ M.funcs = {
     ]=],
     name = 'nextnonblank',
     params = { { 'lnum', 'integer' } },
+    returns = 'integer',
     signature = 'nextnonblank({lnum})',
   },
   nr2char = {
@@ -7669,6 +7768,7 @@ M.funcs = {
     ]=],
     name = 'nr2char',
     params = { { 'expr', 'integer' }, { 'utf8', 'boolean' } },
+    returns = 'string',
     signature = 'nr2char({expr} [, {utf8}])',
   },
   nvim_api__ = {
@@ -7730,6 +7830,7 @@ M.funcs = {
     ]=],
     name = 'pathshorten',
     params = { { 'path', 'string' }, { 'len', 'integer' } },
+    returns = 'string',
     signature = 'pathshorten({path} [, {len}])',
   },
   perleval = {
@@ -7773,6 +7874,7 @@ M.funcs = {
     ]=],
     name = 'pow',
     params = { { 'x', 'number' }, { 'y', 'number' } },
+    returns = 'number',
     signature = 'pow({x}, {y})',
   },
   prevnonblank = {
@@ -7790,6 +7892,7 @@ M.funcs = {
     ]=],
     name = 'prevnonblank',
     params = { { 'lnum', 'integer' } },
+    returns = 'integer',
     signature = 'prevnonblank({lnum})',
   },
   printf = {
@@ -8475,7 +8578,13 @@ M.funcs = {
       <
     ]=],
     name = 'reduce',
-    params = { { 'object', 'any' }, { 'func', 'function' }, { 'initial', 'any' } },
+    generics = { 'T' },
+    params = {
+      { 'object', 'any' },
+      { 'func', 'fun(accumulator: T, current: any): any' },
+      { 'initial', 'any' },
+    },
+    returns = 'T',
     signature = 'reduce({object}, {func} [, {initial}])',
   },
   reg_executing = {
@@ -8679,6 +8788,7 @@ M.funcs = {
     ]=],
     name = 'rename',
     params = { { 'from', 'string' }, { 'to', 'string' } },
+    returns = 'integer',
     signature = 'rename({from}, {to})',
   },
   ['repeat'] = {
@@ -8721,6 +8831,7 @@ M.funcs = {
     fast = true,
     name = 'resolve',
     params = { { 'filename', 'string' } },
+    returns = 'string',
     signature = 'resolve({filename})',
   },
   reverse = {
@@ -8738,7 +8849,9 @@ M.funcs = {
       <
     ]=],
     name = 'reverse',
-    params = { { 'object', 'any' } },
+    generics = { 'T' },
+    params = { { 'object', 'T[]' } },
+    returns = 'T[]',
     signature = 'reverse({object})',
   },
   round = {
@@ -8762,6 +8875,7 @@ M.funcs = {
     float_func = 'round',
     name = 'round',
     params = { { 'expr', 'number' } },
+    returns = 'number',
     signature = 'round({expr})',
   },
   rpcnotify = {
@@ -8774,7 +8888,8 @@ M.funcs = {
       <
     ]=],
     name = 'rpcnotify',
-    params = { { 'channel', 'integer' }, { 'event', 'string' }, { 'args', 'any' } },
+    params = { { 'channel', 'integer' }, { 'event', 'string' }, { '...', 'any' } },
+    returns = 'integer',
     signature = 'rpcnotify({channel}, {event} [, {args}...])',
   },
   rpcrequest = {
@@ -8787,7 +8902,7 @@ M.funcs = {
       <
     ]=],
     name = 'rpcrequest',
-    params = { { 'channel', 'integer' }, { 'method', 'string' }, { 'args', 'any' } },
+    params = { { 'channel', 'integer' }, { 'method', 'string' }, { '...', 'any' } },
     signature = 'rpcrequest({channel}, {method} [, {args}...])',
   },
   rpcstart = {
@@ -8846,6 +8961,7 @@ M.funcs = {
     ]=],
     name = 'screenattr',
     params = { { 'row', 'integer' }, { 'col', 'integer' } },
+    returns = 'integer',
     signature = 'screenattr({row}, {col})',
   },
   screenchar = {
@@ -8864,6 +8980,7 @@ M.funcs = {
     ]=],
     name = 'screenchar',
     params = { { 'row', 'integer' }, { 'col', 'integer' } },
+    returns = 'integer',
     signature = 'screenchar({row}, {col})',
   },
   screenchars = {
@@ -8879,6 +8996,7 @@ M.funcs = {
     ]=],
     name = 'screenchars',
     params = { { 'row', 'integer' }, { 'col', 'integer' } },
+    returns = 'integer[]',
     signature = 'screenchars({row}, {col})',
   },
   screencol = {
@@ -8899,6 +9017,7 @@ M.funcs = {
     ]=],
     name = 'screencol',
     params = {},
+    returns = 'integer[]',
     signature = 'screencol()',
   },
   screenpos = {
@@ -8944,6 +9063,7 @@ M.funcs = {
     ]=],
     name = 'screenrow',
     params = {},
+    returns = 'integer',
     signature = 'screenrow()',
   },
   screenstring = {
@@ -8960,6 +9080,7 @@ M.funcs = {
     ]=],
     name = 'screenstring',
     params = { { 'row', 'integer' }, { 'col', 'integer' } },
+    returns = 'string',
     signature = 'screenstring({row}, {col})',
   },
   search = {
@@ -9079,6 +9200,7 @@ M.funcs = {
       { 'timeout', 'integer' },
       { 'skip', 'string|function' },
     },
+    returns = 'integer',
     signature = 'search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]])',
   },
   searchcount = {
@@ -9401,6 +9523,7 @@ M.funcs = {
     ]=],
     name = 'serverlist',
     params = {},
+    returns = 'string[]',
     signature = 'serverlist()',
   },
   serverstart = {
@@ -9441,6 +9564,7 @@ M.funcs = {
     ]=],
     name = 'serverstart',
     params = { { 'address', 'string' } },
+    returns = 'string',
     signature = 'serverstart([{address}])',
   },
   serverstop = {
@@ -9453,6 +9577,7 @@ M.funcs = {
     ]=],
     name = 'serverstop',
     params = { { 'address', 'string' } },
+    returns = 'integer',
     signature = 'serverstop({address})',
   },
   setbufline = {
@@ -9486,6 +9611,7 @@ M.funcs = {
     ]=],
     name = 'setbufline',
     params = { { 'buf', 'integer|string' }, { 'lnum', 'integer' }, { 'text', 'string|string[]' } },
+    returns = 'integer',
     signature = 'setbufline({buf}, {lnum}, {text})',
   },
   setbufvar = {
@@ -9611,6 +9737,7 @@ M.funcs = {
     ]=],
     name = 'setcmdline',
     params = { { 'str', 'string' }, { 'pos', 'integer' } },
+    returns = 'integer',
     signature = 'setcmdline({str} [, {pos}])',
   },
   setcmdpos = {
@@ -9961,6 +10088,7 @@ M.funcs = {
       { 'action', 'string' },
       { 'what', 'vim.fn.setqflist.what' },
     },
+    returns = 'integer',
     signature = 'setqflist({list} [, {action} [, {what}]])',
   },
   setreg = {
@@ -10137,6 +10265,7 @@ M.funcs = {
     ]=],
     name = 'sha256',
     params = { { 'string', 'string' } },
+    returns = 'string',
     signature = 'sha256({string})',
   },
   shellescape = {
@@ -10177,6 +10306,7 @@ M.funcs = {
     ]=],
     name = 'shellescape',
     params = { { 'string', 'string' }, { 'special', 'boolean' } },
+    returns = 'string',
     signature = 'shellescape({string} [, {special}])',
   },
   shiftwidth = {
@@ -10691,6 +10821,7 @@ M.funcs = {
     ]=],
     name = 'simplify',
     params = { { 'filename', 'string' } },
+    returns = 'string',
     signature = 'simplify({filename})',
   },
   sin = {
@@ -10710,6 +10841,7 @@ M.funcs = {
     float_func = 'sin',
     name = 'sin',
     params = { { 'expr', 'number' } },
+    returns = 'number',
     signature = 'sin({expr})',
   },
   sinh = {
@@ -10859,7 +10991,9 @@ M.funcs = {
       <
     ]=],
     name = 'sort',
-    params = { { 'list', 'any' }, { 'how', 'string|function' }, { 'dict', 'any' } },
+    generics = { 'T' },
+    params = { { 'list', 'T[]' }, { 'how', 'string|function' }, { 'dict', 'any' } },
+    returns = 'T[]',
     signature = 'sort({list} [, {how} [, {dict}]])',
   },
   soundfold = {
@@ -10876,6 +11010,7 @@ M.funcs = {
     ]=],
     name = 'soundfold',
     params = { { 'word', 'string' } },
+    returns = 'string',
     signature = 'soundfold({word})',
   },
   spellbadword = {
@@ -10937,6 +11072,7 @@ M.funcs = {
     ]=],
     name = 'spellsuggest',
     params = { { 'word', 'string' }, { 'max', 'integer' }, { 'capital', 'boolean' } },
+    returns = 'string[]',
     signature = 'spellsuggest({word} [, {max} [, {capital}]])',
   },
   split = {
@@ -10970,6 +11106,7 @@ M.funcs = {
     ]=],
     name = 'split',
     params = { { 'string', 'string' }, { 'pattern', 'string' }, { 'keepempty', 'boolean' } },
+    returns = 'string[]',
     signature = 'split({string} [, {pattern} [, {keepempty}]])',
   },
   sqrt = {
@@ -11153,7 +11290,7 @@ M.funcs = {
       and exists only for backwards-compatibility.
       With UTF-8 composing characters are handled properly: >vim
       	echo str2list("á")		" returns [97, 769]
-
+      <
     ]=],
     name = 'str2list',
     params = { { 'string', 'string' }, { 'utf8', 'boolean' } },
@@ -12188,24 +12325,14 @@ M.funcs = {
     signature = 'tempname()',
   },
   termopen = {
+    deprecated = true,
     args = { 1, 2 },
     desc = [=[
-      Spawns {cmd} in a new pseudo-terminal session connected
-      to the current (unmodified) buffer. Parameters and behavior
-      are the same as |jobstart()| except "pty", "width", "height",
-      and "TERM" are ignored: "height" and "width" are taken from
-      the current window. Note that termopen() implies a "pty" arg
-      to jobstart(), and thus has the implications documented at
-      |jobstart()|.
-
-      Returns the same values as jobstart().
-
-      Terminal environment is initialized as in |jobstart-env|,
-      except $TERM is set to "xterm-256color". Full behavior is
-      described in |terminal|.
+      Use |jobstart()| with `{term: v:true}` instead.
     ]=],
     name = 'termopen',
     params = { { 'cmd', 'string|string[]' }, { 'opts', 'table' } },
+    returns = 'integer',
     signature = 'termopen({cmd} [, {opts}])',
   },
   test_garbagecollect_now = {
@@ -12715,6 +12842,7 @@ M.funcs = {
     ]=],
     name = 'virtcol2col',
     params = { { 'winid', 'integer' }, { 'lnum', 'integer' }, { 'col', 'integer' } },
+    returns = 'integer',
     signature = 'virtcol2col({winid}, {lnum}, {col})',
   },
   visualmode = {
@@ -12739,6 +12867,7 @@ M.funcs = {
     ]=],
     name = 'visualmode',
     params = { { 'expr', 'boolean' } },
+    returns = 'string',
     signature = 'visualmode([{expr}])',
   },
   wait = {
@@ -12896,6 +13025,7 @@ M.funcs = {
     ]=],
     name = 'win_id2win',
     params = { { 'expr', 'integer' } },
+    returns = 'integer',
     signature = 'win_id2win({expr})',
   },
   win_move_separator = {
@@ -13089,6 +13219,7 @@ M.funcs = {
     ]=],
     name = 'winlayout',
     params = { { 'tabnr', 'integer' } },
+    returns = 'any[]',
     signature = 'winlayout([{tabnr}])',
   },
   winline = {
@@ -13141,6 +13272,7 @@ M.funcs = {
     ]=],
     name = 'winnr',
     params = { { 'arg', 'string|integer' } },
+    returns = 'integer',
     signature = 'winnr([{arg}])',
   },
   winrestcmd = {
@@ -13157,6 +13289,7 @@ M.funcs = {
     ]=],
     name = 'winrestcmd',
     params = {},
+    returns = 'string',
     signature = 'winrestcmd()',
   },
   winrestview = {
@@ -13236,6 +13369,7 @@ M.funcs = {
     ]=],
     name = 'winwidth',
     params = { { 'nr', 'integer' } },
+    returns = 'integer',
     signature = 'winwidth({nr})',
   },
   wordcount = {
@@ -13331,7 +13465,8 @@ M.funcs = {
       <
     ]=],
     name = 'xor',
-    params = { { 'expr', 'number' }, { 'expr', 'number' } },
+    params = { { 'expr', 'integer' }, { 'expr', 'integer' } },
+    returns = 'integer',
     signature = 'xor({expr}, {expr})',
   },
 }