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

1 files changed, 592 insertions, 483 deletions

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index f4daacfb7d..3f6deba092 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -15,7 +15,7 @@ error('Cannot require a meta file')
 ---   echo abs(-4)
 --- <  4
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.abs(expr) end
 
@@ -31,7 +31,7 @@ function vim.fn.abs(expr) end
 ---   echo acos(-0.5)
 --- <  2.094395
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.acos(expr) end
 
@@ -47,7 +47,7 @@ function vim.fn.acos(expr) end
 ---
 --- @param object any
 --- @param expr any
---- @return any
+--- @return any # Resulting |List| or |Blob|, or 1 if {object} is not a |List| or a |Blob|.
 function vim.fn.add(object, expr) end
 
 --- Bitwise AND on the two arguments.  The arguments are converted
@@ -57,8 +57,8 @@ function vim.fn.add(object, expr) end
 ---   let flag = and(bits, 0x80)
 --- <
 ---
---- @param expr any
---- @param expr1 any
+--- @param expr number
+--- @param expr1 number
 --- @return integer
 vim.fn['and'] = function(expr, expr1) end
 
@@ -86,7 +86,7 @@ function vim.fn.api_info() end
 --- <
 ---
 --- @param lnum integer
---- @param text any
+--- @param text string|string[]
 --- @return 0|1
 function vim.fn.append(lnum, text) end
 
@@ -110,7 +110,7 @@ function vim.fn.append(lnum, text) end
 --- <However, when {text} is an empty list then no error is given
 --- for an invalid {lnum}, since {lnum} isn't actually used.
 ---
---- @param buf any
+--- @param buf integer|string
 --- @param lnum integer
 --- @param text string
 --- @return 0|1
@@ -195,7 +195,7 @@ function vim.fn.asin(expr) end
 --- Also see |assert_fails()|, |assert_nobeep()| and
 --- |assert-return|.
 ---
---- @param cmd any
+--- @param cmd string
 --- @return 0|1
 function vim.fn.assert_beeps(cmd) end
 
@@ -203,16 +203,17 @@ function vim.fn.assert_beeps(cmd) end
 --- added to |v:errors| and 1 is returned.  Otherwise zero is
 --- returned. |assert-return|
 --- The error is in the form "Expected {expected} but got
---- {actual}".  When {msg} is present it is prefixed to that.
+--- {actual}".  When {msg} is present it is prefixed to that,
+--- along with the location of the assert when run from a script.
 ---
 --- There is no automatic conversion, the String "4" is different
 --- from the Number 4.  And the number 4 is different from the
 --- Float 4.0.  The value of 'ignorecase' is not used here, case
 --- always matters.
 --- Example: >vim
----   assert_equal('foo', 'bar')
---- <Will result in a string to be added to |v:errors|:
----   test.vim line 12: Expected 'foo' but got 'bar' ~
+---   call assert_equal('foo', 'bar', 'baz')
+--- <Will add the following to |v:errors|:
+---   test.vim line 12: baz: Expected 'foo' but got 'bar' ~
 ---
 --- @param expected any
 --- @param actual any
@@ -226,8 +227,10 @@ function vim.fn.assert_equal(expected, actual, msg) end
 --- When {fname-one} or {fname-two} does not exist the error will
 --- mention that.
 ---
+--- @param fname-one string
+--- @param fname-two string
 --- @return 0|1
-function vim.fn.assert_equalfile() end
+function vim.fn.assert_equalfile(fname-one, fname-two) end
 
 --- When v:exception does not contain the string {error} an error
 --- message is added to |v:errors|.  Also see |assert-return|.
@@ -254,25 +257,25 @@ function vim.fn.assert_exception(error, msg) end
 --- When {error} is a string it must be found literally in the
 --- first reported error. Most often this will be the error code,
 --- including the colon, e.g. "E123:". >vim
----   assert_fails('bad cmd', 'E987:')
+---   call assert_fails('bad cmd', 'E987:')
 --- <
 --- When {error} is a |List| with one or two strings, these are
 --- used as patterns.  The first pattern is matched against the
 --- first reported error: >vim
----   assert_fails('cmd', ['E987:.*expected bool'])
+---   call assert_fails('cmd', ['E987:.*expected bool'])
 --- <The second pattern, if present, is matched against the last
 --- reported error.  To only match the last error use an empty
 --- string for the first error: >vim
----   assert_fails('cmd', ['', 'E987:'])
+---   call assert_fails('cmd', ['', 'E987:'])
 --- <
 --- If {msg} is empty then it is not used.  Do this to get the
 --- default message when passing the {lnum} argument.
----
+---           *E1115*
 --- When {lnum} is present and not negative, and the {error}
 --- argument is present and matches, then this is compared with
 --- the line number at which the error was reported. That can be
 --- the line number in a function or in a script.
----
+---           *E1116*
 --- When {context} is present it is used as a pattern and matched
 --- against the context (script name or function name) where
 --- {lnum} is located in.
@@ -280,7 +283,7 @@ function vim.fn.assert_exception(error, msg) end
 --- Note that beeping is not considered an error, and some failing
 --- commands only beep.  Use |assert_beeps()| for those.
 ---
---- @param cmd any
+--- @param cmd string
 --- @param error? any
 --- @param msg? any
 --- @param lnum? integer
@@ -291,7 +294,8 @@ function vim.fn.assert_fails(cmd, error, msg, lnum, context) end
 --- 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}".
---- When {msg} is present it is prepended to that.
+--- When {msg} is present it is prefixed to that, along with the
+--- location of the assert when run from a script.
 --- Also see |assert-return|.
 ---
 --- A value is false when it is zero. When {actual} is not a
@@ -309,17 +313,18 @@ function vim.fn.assert_false(actual, msg) end
 --- but got {actual}".  When {msg} is present it is prefixed to
 --- that.
 ---
---- @param lower any
---- @param upper any
---- @param actual any
---- @param msg? any
+--- @param lower number
+--- @param upper number
+--- @param actual number
+--- @param msg? string
 --- @return 0|1
 function vim.fn.assert_inrange(lower, upper, actual, msg) end
 
 --- When {pattern} does not match {actual} an error message is
 --- added to |v:errors|.  Also see |assert-return|.
 --- The error is in the form "Pattern {pattern} does not match
---- {actual}".  When {msg} is present it is prefixed to that.
+--- {actual}".  When {msg} is present it is prefixed to that,
+--- along with the location of the assert when run from a script.
 ---
 --- {pattern} is used as with |expr-=~|: The matching is always done
 --- like 'magic' was set and 'cpoptions' is empty, no matter what
@@ -330,13 +335,13 @@ function vim.fn.assert_inrange(lower, upper, actual, msg) end
 --- Use both to match the whole text.
 ---
 --- Example: >vim
----   assert_match('^f.*o$', 'foobar')
+---   call assert_match('^f.*o$', 'foobar')
 --- <Will result in a string to be added to |v:errors|:
 ---   test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~
 ---
---- @param pattern any
---- @param actual any
---- @param msg? any
+--- @param pattern string
+--- @param actual string
+--- @param msg? string
 --- @return 0|1
 function vim.fn.assert_match(pattern, actual, msg) end
 
@@ -344,7 +349,7 @@ function vim.fn.assert_match(pattern, actual, msg) end
 --- produces a beep or visual bell.
 --- Also see |assert_beeps()|.
 ---
---- @param cmd any
+--- @param cmd string
 --- @return 0|1
 function vim.fn.assert_nobeep(cmd) end
 
@@ -362,16 +367,16 @@ function vim.fn.assert_notequal(expected, actual, msg) end
 --- |v:errors| when {pattern} matches {actual}.
 --- Also see |assert-return|.
 ---
---- @param pattern any
---- @param actual any
---- @param msg? any
+--- @param pattern string
+--- @param actual string
+--- @param msg? string
 --- @return 0|1
 function vim.fn.assert_notmatch(pattern, actual, msg) end
 
 --- Report a test failure directly, using String {msg}.
 --- Always returns one.
 ---
---- @param msg any
+--- @param msg string
 --- @return 0|1
 function vim.fn.assert_report(msg) end
 
@@ -380,10 +385,11 @@ function vim.fn.assert_report(msg) end
 --- Also see |assert-return|.
 --- A value is |TRUE| when it is a non-zero number or |v:true|.
 --- When {actual} is not a number or |v:true| the assert fails.
---- When {msg} is given it precedes the default message.
+--- When {msg} is given it is prefixed to the default message,
+--- along with the location of the assert when run from a script.
 ---
 --- @param actual any
---- @param msg? any
+--- @param msg? string
 --- @return 0|1
 function vim.fn.assert_true(actual, msg) end
 
@@ -397,7 +403,7 @@ function vim.fn.assert_true(actual, msg) end
 ---   echo atan(-4.01)
 --- <  -1.326405
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.atan(expr) end
 
@@ -412,8 +418,8 @@ function vim.fn.atan(expr) end
 ---   echo atan2(1, -1)
 --- <  2.356194
 ---
---- @param expr1 any
---- @param expr2 any
+--- @param expr1 number
+--- @param expr2 number
 --- @return number
 function vim.fn.atan2(expr1, expr2) end
 
@@ -439,9 +445,9 @@ function vim.fn.blob2list(blob) end
 --- something went wrong, or browsing is not possible.
 ---
 --- @param save any
---- @param title any
---- @param initdir any
---- @param default any
+--- @param title string
+--- @param initdir string
+--- @param default string
 --- @return 0|1
 function vim.fn.browse(save, title, initdir, default) end
 
@@ -456,8 +462,8 @@ function vim.fn.browse(save, title, initdir, default) end
 --- When the "Cancel" button is hit, something went wrong, or
 --- browsing is not possible, an empty string is returned.
 ---
---- @param title any
---- @param initdir any
+--- @param title string
+--- @param initdir string
 --- @return 0|1
 function vim.fn.browsedir(title, initdir) end
 
@@ -729,7 +735,7 @@ function vim.fn.call(func, arglist, dict) end
 ---
 --- Returns 0.0 if {expr} is not a |Float| or a |Number|.
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.ceil(expr) end
 
@@ -742,8 +748,8 @@ function vim.fn.ceil(expr) end
 --- For a socket, there is only one stream, and {stream} should be
 --- omitted.
 ---
---- @param id any
---- @param stream? any
+--- @param id integer
+--- @param stream? string
 --- @return 0|1
 function vim.fn.chanclose(id, stream) end
 
@@ -775,8 +781,8 @@ function vim.fn.changenr() end
 --- was created with `"rpc":v:true` then the channel expects RPC
 --- messages, use |rpcnotify()| and |rpcrequest()| instead.
 ---
---- @param id any
---- @param data any
+--- @param id number
+--- @param data string|string[]
 --- @return 0|1
 function vim.fn.chansend(id, data) end
 
@@ -820,8 +826,9 @@ function vim.fn.charclass(string) end
 --- With the cursor on '세' in line 5 with text "여보세요": >vim
 ---   echo charcol('.')  " returns 3
 ---   echo col('.')    " returns 7
+--- <
 ---
---- @param expr any
+--- @param expr string|integer[]
 --- @param winid? integer
 --- @return integer
 function vim.fn.charcol(expr, winid) end
@@ -861,8 +868,8 @@ function vim.fn.charcol(expr, winid) end
 ---
 --- @param string string
 --- @param idx integer
---- @param countcc? any
---- @param utf16? any
+--- @param countcc? boolean
+--- @param utf16? boolean
 --- @return integer
 function vim.fn.charidx(string, idx, countcc, utf16) end
 
@@ -886,6 +893,7 @@ function vim.fn.charidx(string, idx, countcc, utf16) end
 ---      " ... do some work
 ---      call chdir(save_dir)
 ---   endif
+--- <
 ---
 --- @param dir string
 --- @return string
@@ -907,37 +915,37 @@ function vim.fn.cindent(lnum) end
 --- If {win} is specified, use the window with this number or
 --- window ID instead of the current window.
 ---
---- @param win? any
+--- @param win? integer
 function vim.fn.clearmatches(win) end
 
 --- The result is a Number, which is the byte index of the column
---- position given with {expr}.  The accepted positions are:
----     .      the cursor position
----     $      the end of the cursor line (the result is the
----       number of bytes in the cursor line plus one)
----     'x      position of mark x (if the mark is not set, 0 is
----       returned)
----     v       In Visual mode: the start of the Visual area (the
----       cursor is the end).  When not in Visual mode
----       returns the cursor position.  Differs from |'<| in
----       that it's updated right away.
+--- position given with {expr}.
+--- For accepted positions see |getpos()|.
+--- When {expr} is "$", it means the end of the cursor line, so
+--- the result is the number of bytes in the cursor line plus one.
 --- Additionally {expr} can be [lnum, col]: a |List| with the line
 --- and column number. Most useful when the column is "$", to get
 --- the last column of a specific line.  When "lnum" or "col" is
 --- out of range then col() returns zero.
+---
 --- With the optional {winid} argument the values are obtained for
 --- that window instead of the current window.
+---
 --- To get the line number use |line()|.  To get both use
 --- |getpos()|.
+---
 --- For the screen column position use |virtcol()|.  For the
 --- character position use |charcol()|.
+---
 --- Note that only marks in the current file can be used.
+---
 --- Examples: >vim
 ---   echo col(".")      " column of cursor
 ---   echo col("$")      " length of cursor line plus one
 ---   echo col("'t")      " column of mark t
 ---   echo col("'" .. markname)  " column of mark markname
---- <The first column is 1.  Returns 0 if {expr} is invalid or when
+--- <
+--- The first column is 1.  Returns 0 if {expr} is invalid or when
 --- the window with ID {winid} is not found.
 --- For an uppercase mark the column may actually be in another
 --- buffer.
@@ -946,8 +954,9 @@ function vim.fn.clearmatches(win) end
 --- line.  Also, when using a <Cmd> mapping the cursor isn't
 --- moved, this can be used to obtain the column in Insert mode: >vim
 ---   imap <F2> <Cmd>echo col(".").."\n"<CR>
+--- <
 ---
---- @param expr any
+--- @param expr string|integer[]
 --- @param winid? integer
 --- @return integer
 function vim.fn.col(expr, winid) end
@@ -981,8 +990,8 @@ function vim.fn.col(expr, winid) end
 --- <This isn't very useful, but it shows how it works.  Note that
 --- an empty string is returned to avoid a zero being inserted.
 ---
---- @param startcol any
---- @param matches any
+--- @param startcol integer
+--- @param matches any[]
 function vim.fn.complete(startcol, matches) end
 
 --- Add {expr} to the list of matches.  Only to be used by the
@@ -1065,8 +1074,9 @@ function vim.fn.complete_check() end
 ---   call complete_info(['mode'])
 ---   " Get only 'mode' and 'pum_visible'
 ---   call complete_info(['mode', 'pum_visible'])
+--- <
 ---
---- @param what? any
+--- @param what? any[]
 --- @return table
 function vim.fn.complete_info(what) end
 
@@ -1121,10 +1131,10 @@ function vim.fn.complete_info(what) end
 --- don't fit, a vertical layout is used anyway.  For some systems
 --- the horizontal layout is always used.
 ---
---- @param msg any
---- @param choices? any
---- @param default? any
---- @param type? any
+--- @param msg string
+--- @param choices? string
+--- @param default? integer
+--- @param type? string
 --- @return integer
 function vim.fn.confirm(msg, choices, default, type) end
 
@@ -1150,7 +1160,7 @@ function vim.fn.copy(expr) end
 ---   echo cos(-4.01)
 --- <  -0.646043
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.cos(expr) end
 
@@ -1164,7 +1174,7 @@ function vim.fn.cos(expr) end
 ---   echo cosh(-0.5)
 --- <  -1.127626
 ---
---- @param expr any
+--- @param expr number
 --- @return number
 function vim.fn.cosh(expr) end
 
@@ -1180,10 +1190,10 @@ function vim.fn.cosh(expr) end
 --- occurrences of {expr} is returned. Zero is returned when
 --- {expr} is an empty string.
 ---
---- @param comp any
+--- @param comp string|table|any[]
 --- @param expr any
---- @param ic? any
---- @param start? any
+--- @param ic? boolean
+--- @param start? integer
 --- @return integer
 function vim.fn.count(comp, expr, ic, start) end
 
@@ -1191,7 +1201,7 @@ function vim.fn.count(comp, expr, ic, start) end
 --- from the top of the |context-stack| (see |context-dict|).
 --- If {index} is not given, it is assumed to be 0 (i.e.: top).
 ---
---- @param index? any
+--- @param index? integer
 --- @return table
 function vim.fn.ctxget(index) end
 
@@ -1207,7 +1217,7 @@ function vim.fn.ctxpop() end
 --- which |context-types| to include in the pushed context.
 --- Otherwise, all context types are included.
 ---
---- @param types? any
+--- @param types? string[]
 --- @return any
 function vim.fn.ctxpush(types) end
 
@@ -1216,8 +1226,8 @@ function vim.fn.ctxpush(types) end
 --- {context} is a Dictionary with context data (|context-dict|).
 --- If {index} is not given, it is assumed to be 0 (i.e.: top).
 ---
---- @param context any
---- @param index? any
+--- @param context table
+--- @param index? integer
 --- @return any
 function vim.fn.ctxset(context, index) end
 
@@ -1228,7 +1238,7 @@ function vim.fn.ctxsize() end
 
 --- @param lnum integer
 --- @param col? integer
---- @param off? any
+--- @param off? integer
 --- @return any
 function vim.fn.cursor(lnum, col, off) end
 
@@ -1263,7 +1273,7 @@ function vim.fn.cursor(lnum, col, off) end
 --- position within a <Tab> or after the last character.
 --- Returns 0 when the position could be set, -1 otherwise.
 ---
---- @param list any
+--- @param list integer[]
 --- @return any
 function vim.fn.cursor(list) end
 
@@ -1275,7 +1285,7 @@ function vim.fn.cursor(list) end
 --- Returns |TRUE| if successfully interrupted the program.
 --- Otherwise returns |FALSE|.
 ---
---- @param pid any
+--- @param pid integer
 --- @return any
 function vim.fn.debugbreak(pid) end
 
@@ -1299,7 +1309,7 @@ function vim.fn.debugbreak(pid) end
 --- Also see |copy()|.
 ---
 --- @param expr any
---- @param noref? any
+--- @param noref? boolean
 --- @return any
 function vim.fn.deepcopy(expr, noref) end
 
@@ -1339,9 +1349,9 @@ function vim.fn.delete(fname, flags) end
 --- when using |line()| this refers to the current buffer. Use "$"
 --- to refer to the last line in buffer {buf}.
 ---
---- @param buf any
---- @param first any
---- @param last? any
+--- @param buf integer|string
+--- @param first integer|string
+--- @param last? integer|string
 --- @return any
 function vim.fn.deletebufline(buf, first, last) end
 
@@ -1384,9 +1394,9 @@ function vim.fn.deletebufline(buf, first, last) end
 --- This function can be used by plugins to implement options with
 --- validation and parsing logic.
 ---
---- @param dict any
---- @param pattern any
---- @param callback any
+--- @param dict table
+--- @param pattern string
+--- @param callback function
 --- @return any
 function vim.fn.dictwatcheradd(dict, pattern, callback) end
 
@@ -1395,8 +1405,8 @@ function vim.fn.dictwatcheradd(dict, pattern, callback) end
 --- order for the watcher to be successfully deleted.
 ---
 --- @param dict any
---- @param pattern any
---- @param callback any
+--- @param pattern string
+--- @param callback function
 --- @return any
 function vim.fn.dictwatcherdel(dict, pattern, callback) end
 
@@ -1457,7 +1467,7 @@ function vim.fn.diff_hlID(lnum, col) end
 --- echo digraph_get('aa')    " Returns 'あ'
 --- <
 ---
---- @param chars any
+--- @param chars string
 --- @return any
 function vim.fn.digraph_get(chars) end
 
@@ -1475,7 +1485,7 @@ function vim.fn.digraph_get(chars) end
 --- echo digraph_getlist(1)
 --- <
 ---
---- @param listall? any
+--- @param listall? boolean
 --- @return any
 function vim.fn.digraph_getlist(listall) end
 
@@ -1495,12 +1505,9 @@ function vim.fn.digraph_getlist(listall) end
 --- Example: >vim
 ---   call digraph_set('  ', 'あ')
 --- <
---- Can be used as a |method|: >vim
----   GetString()->digraph_set('あ')
---- <
 ---
---- @param chars any
---- @param digraph any
+--- @param chars string
+--- @param digraph string
 --- @return any
 function vim.fn.digraph_set(chars, digraph) end
 
@@ -1518,11 +1525,7 @@ function vim.fn.digraph_set(chars, digraph) end
 --- <Except that the function returns after the first error,
 --- following digraphs will not be added.
 ---
---- Can be used as a |method|: >vim
----     GetList()->digraph_setlist()
---- <
----
---- @param digraphlist any
+--- @param digraphlist table<integer,string[]>
 --- @return any
 function vim.fn.digraph_setlist(digraphlist) end
 
@@ -1557,7 +1560,7 @@ function vim.fn.environ() end
 --- <Also see |shellescape()| and |fnameescape()|.
 ---
 --- @param string string
---- @param chars any
+--- @param chars string
 --- @return any
 function vim.fn.escape(string, chars) end
 
@@ -1582,25 +1585,32 @@ function vim.fn.eventhandler() end
 --- This function checks if an executable with the name {expr}
 --- exists.  {expr} must be the name of the program without any
 --- arguments.
+---
 --- executable() uses the value of $PATH and/or the normal
---- searchpath for programs.    *PATHEXT*
+--- searchpath for programs.
+---           *PATHEXT*
 --- On MS-Windows the ".exe", ".bat", etc. can optionally be
 --- included.  Then the extensions in $PATHEXT are tried.  Thus if
 --- "foo.exe" does not exist, "foo.exe.bat" can be found.  If
---- $PATHEXT is not set then ".exe;.com;.bat;.cmd" is used.  A dot
+--- $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used.  A dot
 --- by itself can be used in $PATHEXT to try using the name
 --- without an extension.  When 'shell' looks like a Unix shell,
 --- then the name is also tried without adding an extension.
 --- On MS-Windows it only checks if the file exists and is not a
 --- directory, not if it's really executable.
---- On Windows an executable in the same directory as Vim is
---- always found (it is added to $PATH at |startup|).
+--- On MS-Windows an executable in the same directory as the Vim
+--- executable is always found (it's added to $PATH at |startup|).
+---       *NoDefaultCurrentDirectoryInExePath*
+--- On MS-Windows an executable in Vim's current working directory
+--- is also normally found, but this can be disabled by setting
+--- the $NoDefaultCurrentDirectoryInExePath environment variable.
+---
 --- The result is a Number:
 ---   1  exists
 ---   0  does not exist
 --- |exepath()| can be used to get the full path of an executable.
 ---
---- @param expr any
+--- @param expr string
 --- @return 0|1
 function vim.fn.executable(expr) end
 
@@ -1641,8 +1651,8 @@ function vim.fn.execute(command, silent) end
 --- Returns empty string otherwise.
 --- If {expr} starts with "./" the |current-directory| is used.
 ---
---- @param expr any
---- @return any
+--- @param expr string
+--- @return string
 function vim.fn.exepath(expr) end
 
 --- The result is a Number, which is |TRUE| if {expr} is
@@ -1733,7 +1743,7 @@ function vim.fn.exepath(expr) end
 --- <This doesn't check for existence of the "bufcount" variable,
 --- but gets the value of "bufcount", and checks if that exists.
 ---
---- @param expr any
+--- @param expr string
 --- @return 0|1
 function vim.fn.exists(expr) end
 
@@ -1747,7 +1757,7 @@ function vim.fn.exists(expr) end
 ---   echo exp(-1)
 --- <  0.367879
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.exp(expr) end
 
@@ -1916,9 +1926,9 @@ function vim.fn.expandcmd(string, options) end
 --- fails.
 --- Returns {expr1}.  Returns 0 on error.
 ---
---- @param expr1 any
---- @param expr2 any
---- @param expr3? any
+--- @param expr1 table
+--- @param expr2 table
+--- @param expr3? table
 --- @return any
 function vim.fn.extend(expr1, expr2, expr3) end
 
@@ -1926,9 +1936,9 @@ function vim.fn.extend(expr1, expr2, expr3) end
 --- List or Dictionary is created and returned.  {expr1} remains
 --- unchanged.
 ---
---- @param expr1 any
---- @param expr2 any
---- @param expr3? any
+--- @param expr1 table
+--- @param expr2 table
+--- @param expr3? table
 --- @return any
 function vim.fn.extendnew(expr1, expr2, expr3) end
 
@@ -1989,6 +1999,19 @@ function vim.fn.feedkeys(string, mode) end
 --- @return any
 function vim.fn.file_readable(file) end
 
+--- 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.
+--- If a file with name {to} already exists, it will fail.
+--- Note that it does not handle directories (yet).
+---
+--- This function is not available in the |sandbox|.
+---
+--- @param from string
+--- @param to string
+--- @return 0|1
+function vim.fn.filecopy(from, to) end
+
 --- The result is a Number, which is |TRUE| when a file with the
 --- name {file} exists, and can be read.  If {file} doesn't exist,
 --- or is a directory, the result is |FALSE|.  {file} is any
@@ -2070,8 +2093,8 @@ function vim.fn.filewritable(file) end
 --- When {expr2} is a Funcref errors inside a function are ignored,
 --- unless it was defined with the "abort" flag.
 ---
---- @param expr1 any
---- @param expr2 any
+--- @param expr1 string|table
+--- @param expr2 string|function
 --- @return any
 function vim.fn.filter(expr1, expr2) end
 
@@ -2094,7 +2117,7 @@ function vim.fn.filter(expr1, expr2) end
 ---
 --- @param name string
 --- @param path? string
---- @param count? any
+--- @param count? integer
 --- @return any
 function vim.fn.finddir(name, path, count) end
 
@@ -2129,15 +2152,15 @@ function vim.fn.findfile(name, path, count) end
 ---   echo flatten([1, [2, [3, 4]], 5], 1)
 --- <  [1, 2, [3, 4], 5]
 ---
---- @param list any
---- @param maxdepth? any
+--- @param list any[]
+--- @param maxdepth? integer
 --- @return any[]|0
 function vim.fn.flatten(list, maxdepth) end
 
 --- Like |flatten()| but first make a copy of {list}.
 ---
---- @param list any
---- @param maxdepth? any
+--- @param list any[]
+--- @param maxdepth? integer
 --- @return any[]|0
 function vim.fn.flattennew(list, maxdepth) end
 
@@ -2162,7 +2185,7 @@ function vim.fn.flattennew(list, maxdepth) end
 ---   echo float2nr(1.0e-100)
 --- <  0
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.float2nr(expr) end
 
@@ -2178,7 +2201,7 @@ function vim.fn.float2nr(expr) end
 ---   echo floor(4.0)
 --- <  4.0
 ---
---- @param expr any
+--- @param expr number
 --- @return any
 function vim.fn.floor(expr) end
 
@@ -2197,8 +2220,8 @@ function vim.fn.floor(expr) end
 ---   echo fmod(-12.33, 1.22)
 --- <  -0.13
 ---
---- @param expr1 any
---- @param expr2 any
+--- @param expr1 number
+--- @param expr2 number
 --- @return any
 function vim.fn.fmod(expr1, expr2) end
 
@@ -2343,8 +2366,8 @@ function vim.fn.foldtextresult(lnum) end
 --- When {expr2} is a Funcref errors inside a function are ignored,
 --- unless it was defined with the "abort" flag.
 ---
---- @param expr1 any
---- @param expr2 any
+--- @param expr1 string|table
+--- @param expr2 string|function
 --- @return any
 function vim.fn.foreach(expr1, expr2) end
 
@@ -2486,7 +2509,7 @@ vim.fn['function'] = function(name, arglist, dict) end
 --- it's safe to perform.  This is when waiting for the user to
 --- type a character.
 ---
---- @param atexit? any
+--- @param atexit? boolean
 --- @return any
 function vim.fn.garbagecollect(atexit) end
 
@@ -2523,12 +2546,25 @@ function vim.fn.get(blob, idx, default) end
 --- @return any
 function vim.fn.get(dict, key, default) end
 
---- Get item {what} from Funcref {func}.  Possible values for
+--- Get item {what} from |Funcref| {func}.  Possible values for
 --- {what} are:
----   "name"  The function name
----   "func"  The function
----   "dict"  The dictionary
----   "args"  The list with arguments
+---   "name"    The function name
+---   "func"    The function
+---   "dict"    The dictionary
+---   "args"    The list with arguments
+---   "arity"   A dictionary with information about the number of
+---       arguments accepted by the function (minus the
+---       {arglist}) with the following fields:
+---     required    the number of positional arguments
+---     optional    the number of optional arguments,
+---           in addition to the required ones
+---     varargs     |TRUE| if the function accepts a
+---           variable number of arguments |...|
+---
+---     Note: There is no error, if the {arglist} of
+---     the Funcref contains more arguments than the
+---     Funcref expects, it's not validated.
+---
 --- Returns zero on error.
 ---
 --- @param func function
@@ -2634,8 +2670,9 @@ function vim.fn.getbufinfo(dict) end
 ---
 --- Example: >vim
 ---   let lines = getbufline(bufnr("myfile"), 1, "$")
+--- <
 ---
---- @param buf any
+--- @param buf integer|string
 --- @param lnum integer
 --- @param end_? integer
 --- @return any
@@ -2669,7 +2706,7 @@ function vim.fn.getbufoneline(buf, lnum) end
 ---   let bufmodified = getbufvar(1, "&mod")
 ---   echo "todo myvar = " .. getbufvar("todo", "myvar")
 ---
---- @param buf any
+--- @param buf integer|string
 --- @param varname string
 --- @param def? any
 --- @return any
@@ -2766,8 +2803,9 @@ function vim.fn.getchangelist(buf) end
 ---   endfunction
 --- <
 ---
+--- @param expr? 0|1
 --- @return integer
-function vim.fn.getchar() end
+function vim.fn.getchar(expr) end
 
 --- The result is a Number which is the state of the modifiers for
 --- the last obtained character with getchar() or in another way.
@@ -2800,7 +2838,7 @@ function vim.fn.getcharmod() end
 ---   getpos('.')    returns [0, 5, 7, 0]
 --- <
 ---
---- @param expr any
+--- @param expr string
 --- @return integer[]
 function vim.fn.getcharpos(expr) end
 
@@ -2823,7 +2861,7 @@ function vim.fn.getcharpos(expr) end
 ---   nnoremap <expr> , getcharsearch().forward ? ',' : ';'
 --- <Also see |setcharsearch()|.
 ---
---- @return table[]
+--- @return table
 function vim.fn.getcharsearch() end
 
 --- Get a single character from the user or input stream as a
@@ -2837,27 +2875,28 @@ function vim.fn.getcharsearch() end
 --- Otherwise this works like |getchar()|, except that a number
 --- result is converted to a string.
 ---
+--- @param expr? 0|1
 --- @return string
-function vim.fn.getcharstr() end
+function vim.fn.getcharstr(expr) end
 
 --- Return the type of the current command-line completion.
 --- Only works when the command line is being edited, thus
 --- requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
 --- See |:command-completion| for the return string.
---- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
---- |setcmdline()|.
+--- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
+--- |getcmdprompt()| and |setcmdline()|.
 --- Returns an empty string when completion is not defined.
 ---
 --- @return string
 function vim.fn.getcmdcompltype() end
 
---- Return the current command-line.  Only works when the command
---- line is being edited, thus requires use of |c_CTRL-\_e| or
---- |c_CTRL-R_=|.
+--- Return the current command-line input.  Only works when the
+--- command line is being edited, thus requires use of
+--- |c_CTRL-\_e| or |c_CTRL-R_=|.
 --- Example: >vim
 ---   cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
---- <Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and
---- |setcmdline()|.
+--- <Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()|,
+--- |getcmdprompt()| and |setcmdline()|.
 --- Returns an empty string when entering a password or using
 --- |inputsecret()|.
 ---
@@ -2869,12 +2908,22 @@ function vim.fn.getcmdline() end
 --- Only works when editing the command line, thus requires use of
 --- |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
 --- Returns 0 otherwise.
---- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
---- |setcmdline()|.
+--- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()|,
+--- |getcmdprompt()| and |setcmdline()|.
 ---
 --- @return integer
 function vim.fn.getcmdpos() end
 
+--- Return the current command-line prompt when using functions
+--- like |input()| or |confirm()|.
+--- Only works when the command line is being edited, thus
+--- requires use of |c_CTRL-\_e| or |c_CTRL-R_=|.
+--- Also see |getcmdtype()|, |getcmdline()|, |getcmdpos()|,
+--- |setcmdpos()| and |setcmdline()|.
+---
+--- @return string
+function vim.fn.getcmdprompt() end
+
 --- Return the screen position of the cursor in the command line
 --- as a byte count.  The first column is 1.
 --- Instead of |getcmdpos()|, it adds the prompt position.
@@ -2927,6 +2976,7 @@ function vim.fn.getcmdwintype() end
 --- customlist,{func} custom completion, defined via {func}
 --- diff_buffer  |:diffget| and |:diffput| completion
 --- dir    directory names
+--- dir_in_path  directory names in |'cdpath'|
 --- environment  environment variable names
 --- event    autocommand events
 --- expression  Vim expression
@@ -2979,9 +3029,9 @@ function vim.fn.getcmdwintype() end
 --- If there are no matches, an empty list is returned.  An
 --- invalid value for {type} produces an error.
 ---
---- @param pat any
---- @param type any
---- @param filtered? any
+--- @param pat string
+--- @param type string
+--- @param filtered? boolean
 --- @return string[]
 function vim.fn.getcompletion(pat, type, filtered) end
 
@@ -3227,7 +3277,7 @@ function vim.fn.getline(lnum, end_) end
 --- <
 ---
 --- @param nr integer
---- @param what? any
+--- @param what? table
 --- @return any
 function vim.fn.getloclist(nr, what) end
 
@@ -3249,8 +3299,8 @@ function vim.fn.getloclist(nr, what) end
 --- Refer to |getpos()| for getting information about a specific
 --- mark.
 ---
---- @param buf? any
---- @return any
+--- @param buf? integer?
+--- @return vim.fn.getmarklist.ret.item[]
 function vim.fn.getmarklist(buf) end
 
 --- Returns a |List| with all matches previously defined for the
@@ -3284,7 +3334,7 @@ function vim.fn.getmarklist(buf) end
 ---   unlet m
 --- <
 ---
---- @param win? any
+--- @param win? integer
 --- @return any
 function vim.fn.getmatches(win) end
 
@@ -3327,9 +3377,34 @@ function vim.fn.getmousepos() end