feat(docs): generate builtin.txt (#24493)

- eval.lua is now the source of truth.

- Formatting is much more consistent.

- Fixed Lua type generation for polymorphic functions (get(), etc).

- Removed "Overview" section from builtin.txt
  - Can generate this if we really want it.

- Moved functions from sign.txt and testing.txt into builtin.txt.

- Removed the *timer* *timers* tags since libuv timers via vim.uv should be preferred.

- Removed the temp-file-name tag from tempname()

- Moved lueval() from lua.txt to builtin.txt.

* Fix indent

* fixup!

* fixup! fixup!

* fixup! better tag formatting

* fixup: revert changes no longer needed

* fixup! CI

---------

Co-authored-by: zeertzjq <zeertzjq@outlook.com>

1 files changed, 450 insertions, 125 deletions

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 409c288036..82213324e3 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -18,7 +18,7 @@
 ---   Compute()->abs()
 ---
 --- @param expr any
---- @return any
+--- @return number
 function vim.fn.abs(expr) end
 
 --- Return the arc cosine of {expr} measured in radians, as a
@@ -68,7 +68,7 @@ function vim.fn.add(object, expr) end
 ---
 --- @param expr any
 --- @param expr1 any
---- @return any
+--- @return integer
 vim.fn['and'] = function(expr, expr1) end
 
 --- Returns Dictionary of |api-metadata|.
@@ -76,7 +76,7 @@ vim.fn['and'] = function(expr, expr1) end
 --- View it in a nice human-readable format: >
 ---        :lua vim.print(vim.fn.api_info())
 ---
---- @return any
+--- @return table
 function vim.fn.api_info() end
 
 --- When {text} is a |List|: Append each item of the |List| as a
@@ -96,7 +96,7 @@ function vim.fn.api_info() end
 ---
 --- @param lnum integer
 --- @param text any
---- @return any
+--- @return 0|1
 function vim.fn.append(lnum, text) end
 
 --- Like |append()| but append the text in buffer {expr}.
@@ -122,8 +122,8 @@ function vim.fn.append(lnum, text) end
 ---
 --- @param buf any
 --- @param lnum integer
---- @param text any
---- @return any
+--- @param text string
+--- @return 0|1
 function vim.fn.appendbufline(buf, lnum, text) end
 
 --- The result is the number of files in the argument list.  See
@@ -139,6 +139,7 @@ function vim.fn.appendbufline(buf, lnum, text) end
 --- @return integer
 function vim.fn.argc(winid) end
 
+--- The result is the current index in the argument list.  0 is
 --- the first file.  argc() - 1 is the last one.  See |arglist|.
 ---
 --- @return integer
@@ -180,7 +181,7 @@ function vim.fn.arglistid(winnr, tabnr) end
 ---
 --- @param nr? integer
 --- @param winid? integer
---- @return any
+--- @return string|string[]
 function vim.fn.argv(nr, winid) end
 
 --- Return the arc sine of {expr} measured in radians, as a |Float|
@@ -197,13 +198,10 @@ function vim.fn.argv(nr, winid) end
 ---
 --- Can also be used as a |method|: >
 ---   Compute()->asin()
----
----
---- assert_ functions are documented here: |assert-functions-details|
----
+--- <
 ---
 --- @param expr any
---- @return any
+--- @return number
 function vim.fn.asin(expr) end
 
 --- Run {cmd} and add an error message to |v:errors| if it does
@@ -214,6 +212,7 @@ function vim.fn.asin(expr) end
 --- Can also be used as a |method|: >
 ---   GetCmd()->assert_beeps()
 --- <
+---
 --- @param cmd any
 --- @return 0|1
 function vim.fn.assert_beeps(cmd) end
@@ -251,7 +250,7 @@ function vim.fn.assert_equal(expected, actual, msg) end
 --- Can also be used as a |method|: >
 ---   GetLog()->assert_equalfile('expected.log')
 ---
---- @return any
+--- @return 0|1
 function vim.fn.assert_equalfile() end
 
 --- When v:exception does not contain the string {error} an error
@@ -266,6 +265,7 @@ function vim.fn.assert_equalfile() end
 ---     call assert_exception('E492:')
 ---   endtry
 --- <
+---
 --- @param error any
 --- @param msg? any
 --- @return 0|1
@@ -367,6 +367,7 @@ function vim.fn.assert_inrange(lower, upper, actual, msg) end
 --- Can also be used as a |method|: >
 ---   getFile()->assert_match('foo.*')
 --- <
+---
 --- @param pattern any
 --- @param actual any
 --- @param msg? any
@@ -380,6 +381,7 @@ function vim.fn.assert_match(pattern, actual, msg) end
 --- Can also be used as a |method|: >
 ---   GetCmd()->assert_nobeep()
 --- <
+---
 --- @param cmd any
 --- @return 0|1
 function vim.fn.assert_nobeep(cmd) end
@@ -391,10 +393,12 @@ function vim.fn.assert_nobeep(cmd) end
 --- Can also be used as a |method|: >
 ---   mylist->assert_notequal([1, 2, 3])
 ---
+--- <
+---
 --- @param expected any
 --- @param actual any
 --- @param msg? any
---- @return any
+--- @return 0|1
 function vim.fn.assert_notequal(expected, actual, msg) end
 
 --- The opposite of `assert_match()`: add an error message to
@@ -403,12 +407,12 @@ function vim.fn.assert_notequal(expected, actual, msg) end
 ---
 --- Can also be used as a |method|: >
 ---   getFile()->assert_notmatch('bar.*')
----
+--- <
 ---
 --- @param pattern any
 --- @param actual any
 --- @param msg? any
---- @return any
+--- @return 0|1
 function vim.fn.assert_notmatch(pattern, actual, msg) end
 
 --- Report a test failure directly, using String {msg}.
@@ -416,10 +420,10 @@ function vim.fn.assert_notmatch(pattern, actual, msg) end
 ---
 --- Can also be used as a |method|: >
 ---   GetMessage()->assert_report()
----
+--- <
 ---
 --- @param msg any
---- @return any
+--- @return 0|1
 function vim.fn.assert_report(msg) end
 
 --- When {actual} is not true an error message is added to
@@ -435,7 +439,7 @@ function vim.fn.assert_report(msg) end
 ---
 --- @param actual any
 --- @param msg? any
---- @return any
+--- @return 0|1
 function vim.fn.assert_true(actual, msg) end
 
 --- Return the principal value of the arc tangent of {expr}, in
@@ -484,8 +488,9 @@ function vim.fn.atan2(expr1, expr2) end
 --- Can also be used as a |method|: >
 ---   GetBlob()->blob2list()
 --- <
+---
 --- @param blob any
---- @return any
+--- @return any[]
 function vim.fn.blob2list(blob) end
 
 --- Put up a file requester.  This only works when "has("browse")"
@@ -502,7 +507,7 @@ function vim.fn.blob2list(blob) end
 --- @param title any
 --- @param initdir any
 --- @param default any
---- @return any
+--- @return 0|1
 function vim.fn.browse(save, title, initdir, default) end
 
 --- Put up a directory requester.  This only works when
@@ -518,7 +523,7 @@ function vim.fn.browse(save, title, initdir, default) end
 ---
 --- @param title any
 --- @param initdir any
---- @return any
+--- @return 0|1
 function vim.fn.browsedir(title, initdir) end
 
 --- Add a buffer to the buffer list with name {name} (must be a
@@ -570,14 +575,23 @@ function vim.fn.bufexists(buf) end
 
 --- @deprecated
 --- Obsolete name for |bufexists()|.
+---
+--- @param ... any
+--- @return 0|1
 function vim.fn.buffer_exists(...) end
 
 --- @deprecated
 --- Obsolete name for |bufname()|.
+---
+--- @param ... any
+--- @return string
 function vim.fn.buffer_name(...) end
 
 --- @deprecated
 --- Obsolete name for |bufnr()|.
+---
+--- @param ... any
+--- @return integer
 function vim.fn.buffer_number(...) end
 
 --- The result is a Number, which is |TRUE| if a buffer called
@@ -649,6 +663,7 @@ function vim.fn.bufloaded(buf) end
 ---   bufname("%")    name of current buffer
 ---   bufname("file2")  name of buffer where "file2" matches.
 --- <
+---
 --- @param buf? any
 --- @return string
 function vim.fn.bufname(buf) end
@@ -796,6 +811,7 @@ function vim.fn.byteidxcomp(expr, nr, utf16) end
 ---
 --- Can also be used as a |method|: >
 ---   GetFunc()->call([arg, arg], dict)
+--- <
 ---
 --- @param func any
 --- @param arglist any
@@ -818,9 +834,10 @@ function vim.fn.call(func, arglist, dict) end
 ---
 --- Can also be used as a |method|: >
 ---   Compute()->ceil()
+--- <
 ---
 --- @param expr any
---- @return any
+--- @return number
 function vim.fn.ceil(expr) end
 
 --- Close a channel or a specific stream associated with it.
@@ -834,7 +851,7 @@ function vim.fn.ceil(expr) end
 ---
 --- @param id any
 --- @param stream? any
---- @return any
+--- @return 0|1
 function vim.fn.chanclose(id, stream) end
 
 --- Return the number of the most recent change.  This is the same
@@ -865,10 +882,9 @@ 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
---- @return any
+--- @return 0|1
 function vim.fn.chansend(id, data) end
 
 --- Return Number value of the first char in {string}.
@@ -890,7 +906,7 @@ function vim.fn.chansend(id, data) end
 ---
 --- @param string string
 --- @param utf8? any
---- @return any
+--- @return 0|1
 function vim.fn.char2nr(string, utf8) end
 
 --- Return the character class of the first character in {string}.
@@ -903,9 +919,8 @@ function vim.fn.char2nr(string, utf8) end
 --- The class is used in patterns and word motions.
 --- Returns 0 if {string} is not a |String|.
 ---
----
 --- @param string string
---- @return any
+--- @return 0|1|2|3|'other'
 function vim.fn.charclass(string) end
 
 --- Same as |col()| but returns the character index of the column
@@ -919,9 +934,10 @@ function vim.fn.charclass(string) end
 --- <Can also be used as a |method|: >
 ---   GetPos()->col()
 --- <
+---
 --- @param expr any
 --- @param winid? integer
---- @return any
+--- @return integer
 function vim.fn.charcol(expr, winid) end
 
 --- Return the character index of the byte at {idx} in {string}.
@@ -963,7 +979,7 @@ function vim.fn.charcol(expr, winid) end
 --- @param idx integer
 --- @param countcc? any
 --- @param utf16? any
---- @return any
+--- @return integer
 function vim.fn.charidx(string, idx, countcc, utf16) end
 
 --- Change the current working directory to {dir}.  The scope of
@@ -990,8 +1006,9 @@ function vim.fn.charidx(string, idx, countcc, utf16) end
 --- <Can also be used as a |method|: >
 ---   GetDir()->chdir()
 --- <
+---
 --- @param dir string
---- @return any
+--- @return string
 function vim.fn.chdir(dir) end
 
 --- Get the amount of indent for line {lnum} according the C
@@ -1005,7 +1022,7 @@ function vim.fn.chdir(dir) end
 ---   GetLnum()->cindent()
 ---
 --- @param lnum integer
---- @return any
+--- @return integer
 function vim.fn.cindent(lnum) end
 
 --- Clears all matches previously defined for the current window
@@ -1016,8 +1033,8 @@ function vim.fn.cindent(lnum) end
 --- Can also be used as a |method|: >
 ---   GetWin()->clearmatches()
 --- <
+---
 --- @param win? any
---- @return any
 function vim.fn.clearmatches(win) end
 
 --- The result is a Number, which is the byte index of the column
@@ -1088,8 +1105,8 @@ function vim.fn.col(expr, winid) end
 ---
 ---   func ListMonths()
 ---     call complete(col('.'), ['January', 'February', 'March',
---- \ 'April', 'May', 'June', 'July', 'August', 'September',
---- \ 'October', 'November', 'December'])
+---       \ 'April', 'May', 'June', 'July', 'August', 'September',
+---       \ 'October', 'November', 'December'])
 ---     return ''
 ---   endfunc
 --- <This isn't very useful, but it shows how it works.  Note that
@@ -1125,7 +1142,6 @@ function vim.fn.complete_add(expr) end
 --- Only to be used by the function specified with the
 --- 'completefunc' option.
 ---
----
 --- @return 0|1
 function vim.fn.complete_check() end
 
@@ -1189,6 +1205,7 @@ function vim.fn.complete_check() end
 --- <Can also be used as a |method|: >
 ---   GetItems()->complete_info()
 --- <
+---
 --- @param what? any
 --- @return table
 function vim.fn.complete_info(what) end
@@ -1247,13 +1264,15 @@ function vim.fn.complete_info(what) end
 --- Can also be used as a |method|in: >
 ---   BuildMessage()->confirm("&Yes\n&No")
 --- <
+---
 --- @param msg any
 --- @param choices? any
 --- @param default? any
 --- @param type? any
---- @return any
+--- @return integer
 function vim.fn.confirm(msg, choices, default, type) end
 
+--- Make a copy of {expr}.  For Numbers and Strings this isn't
 --- different from using {expr} directly.
 --- When {expr} is a |List| a shallow copy is created.  This means
 --- that the original |List| can be changed without changing the
@@ -1281,7 +1300,7 @@ function vim.fn.copy(expr) end
 ---   Compute()->cos()
 ---
 --- @param expr any
---- @return any
+--- @return number
 function vim.fn.cos(expr) end
 
 --- Return the hyperbolic cosine of {expr} as a |Float| in the range
@@ -1298,7 +1317,7 @@ function vim.fn.cos(expr) end
 ---   Compute()->cosh()
 ---
 --- @param expr any
---- @return any
+--- @return number
 function vim.fn.cosh(expr) end
 
 --- Return the number of times an item with value {expr} appears
@@ -1316,11 +1335,12 @@ function vim.fn.cosh(expr) end
 --- Can also be used as a |method|: >
 ---   mylist->count(val)
 --- <
+---
 --- @param comp any
 --- @param expr any
 --- @param ic? any
 --- @param start? any
---- @return any
+--- @return integer
 function vim.fn.count(comp, expr, ic, start) end
 
 --- Returns a |Dictionary| representing the |context| at {index}
@@ -1328,7 +1348,7 @@ function vim.fn.count(comp, expr, ic, start) end
 --- If {index} is not given, it is assumed to be 0 (i.e.: top).
 ---
 --- @param index? any
---- @return any
+--- @return table
 function vim.fn.ctxget(index) end
 
 --- Pops and restores the |context| at the top of the
@@ -1362,6 +1382,12 @@ function vim.fn.ctxset(context, index) end
 --- @return any
 function vim.fn.ctxsize() end
 
+--- @param lnum integer
+--- @param col? integer
+--- @param off? any
+--- @return any
+function vim.fn.cursor(lnum, col, off) end
+
 --- Positions the cursor at the column (byte count) {col} in the
 --- line {lnum}.  The first column is one.
 ---
@@ -1410,6 +1436,7 @@ function vim.fn.cursor(list) end
 ---
 --- Can also be used as a |method|: >
 ---   GetPid()->debugbreak()
+--- <
 ---
 --- @param pid any
 --- @return any
@@ -1484,6 +1511,7 @@ function vim.fn.delete(fname, flags) end
 --- Can also be used as a |method|: >
 ---   GetBuffer()->deletebufline(1)
 --- <
+---
 --- @param buf any
 --- @param first any
 --- @param last? any
@@ -1545,6 +1573,7 @@ function vim.fn.dictwatcheradd(dict, pattern, callback) end
 --- @return any
 function vim.fn.dictwatcherdel(dict, pattern, callback) end
 
+--- Returns |TRUE| when autocommands are being executed and the
 --- FileType event has been triggered at least once.  Can be used
 --- to avoid triggering the FileType event again in the scripts
 --- that detect the file type. |FileType|
@@ -1718,11 +1747,13 @@ function vim.fn.environ() end
 --- Can also be used as a |method|: >
 ---   GetText()->escape(' \')
 --- <
+---
 --- @param string string
 --- @param chars any
 --- @return any
 function vim.fn.escape(string, chars) end
 
+--- Evaluate {string} and return the result.  Especially useful to
 --- turn the result of |string()| back into the original value.
 --- This works for Numbers, Floats, Strings, Blobs and composites
 --- of them.  Also works for |Funcref|s that refer to existing
@@ -1815,10 +1846,12 @@ function vim.fn.execute(command, silent) end
 --- Can also be used as a |method|: >
 ---   GetCommand()->exepath()
 --- <
+---
 --- @param expr any
 --- @return any
 function vim.fn.exepath(expr) end
 
+--- The result is a Number, which is |TRUE| if {expr} is
 --- defined, zero otherwise.
 ---
 --- For checking for a supported feature use |has()|.
@@ -2051,6 +2084,7 @@ function vim.fn.expand(string, nosuf, list) end
 --- Can also be used as a |method|: >
 ---   GetCommand()->expandcmd()
 --- <
+---
 --- @param string string
 --- @param options? table
 --- @return any
@@ -2093,7 +2127,7 @@ function vim.fn.expandcmd(string, options) end
 ---
 --- Can also be used as a |method|: >
 ---   mylist->extend(otherlist)
----
+--- <
 ---
 --- @param expr1 any
 --- @param expr2 any
@@ -2105,7 +2139,6 @@ 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
@@ -2166,7 +2199,10 @@ function vim.fn.feedkeys(string, mode) end
 
 --- @deprecated
 --- Obsolete name for |filereadable()|.
-function vim.fn.file_readable(...) end
+---
+--- @param file string
+--- @return any
+function vim.fn.file_readable(file) 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,
@@ -2319,6 +2355,7 @@ function vim.fn.findfile(name, path, count) end
 --- Can also be used as a |method|: >
 ---   mylist->flatten()
 --- <
+---
 --- @param list any
 --- @param maxdepth? any
 --- @return any[]|0
@@ -2326,7 +2363,6 @@ function vim.fn.flatten(list, maxdepth) end
 
 --- Like |flatten()| but first make a copy of {list}.
 ---
----
 --- @param list any
 --- @param maxdepth? any
 --- @return any[]|0
@@ -2488,10 +2524,12 @@ function vim.fn.foldclosedend(lnum) end
 --- Can also be used as a |method|: >
 ---   GetLnum()->foldlevel()
 --- <
+---
 --- @param lnum integer
 --- @return integer
 function vim.fn.foldlevel(lnum) end
 
+--- Returns a String, to be displayed for a closed fold.  This is
 --- the default function used for the 'foldtext' option and should
 --- only be called from evaluating 'foldtext'.  It uses the
 --- |v:foldstart|, |v:foldend| and |v:folddashes| variables.
@@ -2521,6 +2559,7 @@ function vim.fn.foldtext() end
 --- Can also be used as a |method|: >
 ---   GetLnum()->foldtextresult()
 --- <
+---
 --- @param lnum integer
 --- @return string
 function vim.fn.foldtextresult(lnum) end
@@ -2539,6 +2578,7 @@ function vim.fn.foldtextresult(lnum) end
 --- Can also be used as a |method|: >
 ---   GetName()->fullcommand()
 --- <
+---
 --- @param name string
 --- @return string
 function vim.fn.fullcommand(name) end
@@ -2557,6 +2597,7 @@ function vim.fn.fullcommand(name) end
 --- Can also be used as a |method|: >
 ---   GetFuncname()->funcref([arg])
 --- <
+---
 --- @param name string
 --- @param arglist? any
 --- @param dict? any
@@ -2672,6 +2713,41 @@ vim.fn['function'] = function(name, arglist, dict) end
 --- @return any
 function vim.fn.garbagecollect(atexit) end
 
+--- Get item {idx} from |List| {list}.  When this item is not
+--- available return {default}.  Return zero when {default} is
+--- omitted.
+--- Can also be used as a |method|: >
+---   mylist->get(idx)
+---
+--- @param list any[]
+--- @param idx integer
+--- @param default? any
+--- @return any
+function vim.fn.get(list, idx, default) end
+
+--- Get byte {idx} from |Blob| {blob}.  When this byte is not
+--- available return {default}.  Return -1 when {default} is
+--- omitted.
+---
+--- @param blob string
+--- @param idx integer
+--- @param default? any
+--- @return any
+function vim.fn.get(blob, idx, default) end
+
+--- Get item with key {key} from |Dictionary| {dict}.  When this
+--- item is not available return {default}.  Return zero when
+--- {default} is omitted.  Useful example: >
+---   let val = get(g:, 'var_name', 'default')
+--- <This gets the value of g:var_name if it exists, and uses
+--- "default" when it does not exist.
+---
+--- @param dict table<string,any>
+--- @param key string
+--- @param default? any
+--- @return any
+function vim.fn.get(dict, key, default) end
+
 --- Get item {what} from Funcref {func}.  Possible values for
 --- {what} are:
 ---   "name"  The function name
@@ -2680,11 +2756,15 @@ function vim.fn.garbagecollect(atexit) end
 ---   "args"  The list with arguments
 --- Returns zero on error.
 ---
---- @param func any
---- @param what any
+--- @param func function
+--- @param what string
 --- @return any
 function vim.fn.get(func, what) end
 
+--- @param buf? integer|string
+--- @return any
+function vim.fn.getbufinfo(buf) end
+
 --- Get information about buffers as a List of Dictionaries.
 ---
 --- Without an argument information about all the buffers is
@@ -2753,7 +2833,7 @@ function vim.fn.get(func, what) end
 ---   GetBufnr()->getbufinfo()
 --- <
 ---
---- @param dict? any
+--- @param dict? table<string,any>
 --- @return any
 function vim.fn.getbufinfo(dict) end
 
@@ -2784,9 +2864,10 @@ function vim.fn.getbufinfo(dict) end
 --- <Can also be used as a |method|: >
 ---   GetBufnr()->getbufline(lnum)
 --- <
+---
 --- @param buf any
 --- @param lnum integer
---- @param end_? any
+--- @param end_? integer
 --- @return any
 function vim.fn.getbufline(buf, lnum, end_) end
 
@@ -2821,6 +2902,7 @@ function vim.fn.getbufoneline(buf, lnum) end
 --- <Can also be used as a |method|: >
 ---   GetBufnr()->getbufvar(varname)
 --- <
+---
 --- @param buf any
 --- @param varname string
 --- @param def? any
@@ -2832,7 +2914,6 @@ function vim.fn.getbufvar(buf, varname, def) end
 --- |setcellwidths()|.  If no character ranges have their cell
 --- widths overridden, an empty List is returned.
 ---
----
 --- @return any
 function vim.fn.getcellwidths() end
 
@@ -2854,8 +2935,8 @@ function vim.fn.getcellwidths() end
 --- Can also be used as a |method|: >
 ---   GetBufnr()->getchangelist()
 ---
---- @param buf? any
---- @return any
+--- @param buf? integer|string
+--- @return table[]
 function vim.fn.getchangelist(buf) end
 
 --- Get a single character from the user or input stream.
@@ -2921,6 +3002,7 @@ function vim.fn.getchangelist(buf) end
 ---   :  endwhile
 ---   :endfunction
 --- <
+---
 --- @return integer
 function vim.fn.getchar() end
 
@@ -2958,7 +3040,7 @@ function vim.fn.getcharmod() end
 ---   GetMark()->getcharpos()
 ---
 --- @param expr any
---- @return any
+--- @return integer[]
 function vim.fn.getcharpos(expr) end
 
 --- Return the current character search information as a {dict}
@@ -2980,8 +3062,7 @@ function vim.fn.getcharpos(expr) end
 ---   :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
 --- <Also see |setcharsearch()|.
 ---
----
---- @return any
+--- @return table[]
 function vim.fn.getcharsearch() end
 
 --- Get a single character from the user or input stream as a
@@ -3030,7 +3111,7 @@ function vim.fn.getcmdline() end
 --- Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and
 --- |setcmdline()|.
 ---
---- @return any
+--- @return integer
 function vim.fn.getcmdpos() end
 
 --- Return the screen position of the cursor in the command line
@@ -3137,6 +3218,7 @@ function vim.fn.getcmdwintype() end
 --- Can also be used as a |method|: >
 ---   GetPattern()->getcompletion('color')
 --- <
+---
 --- @param pat any
 --- @param type any
 --- @param filtered? any
@@ -3170,6 +3252,7 @@ function vim.fn.getcompletion(pat, type, filtered) end
 --- Can also be used as a |method|: >
 ---   GetWinid()->getcurpos()
 --- <
+---
 --- @param winid? integer
 --- @return any
 function vim.fn.getcurpos(winid) end
@@ -3339,6 +3422,7 @@ function vim.fn.getftype(fname) end
 ---
 --- Can also be used as a |method|: >
 ---   GetWinnr()->getjumplist()
+--- <
 ---
 --- @param winnr? integer
 --- @param tabnr? integer
@@ -3374,7 +3458,7 @@ function vim.fn.getjumplist(winnr, tabnr) end
 ---
 --- @param lnum integer
 --- @param end_? any
---- @return any
+--- @return string|string[]
 function vim.fn.getline(lnum, end_) end
 
 --- Returns a |List| with all the entries in the location list for
@@ -3406,7 +3490,7 @@ function vim.fn.getline(lnum, end_) end
 --- Examples (See also |getqflist-examples|): >
 ---   :echo getloclist(3, {'all': 0})
 ---   :echo getloclist(5, {'filewinid': 0})
----
+--- <
 ---
 --- @param nr integer
 --- @param what? any
@@ -3448,26 +3532,27 @@ function vim.fn.getmarklist(buf) end
 --- an empty list is returned.
 --- Example: >vim
 ---   :echo getmatches()
---- >
----        [{"group": "MyGroup1", "pattern": "TODO",
+--- < >
+---   [{"group": "MyGroup1", "pattern": "TODO",
 ---   "priority": 10, "id": 1}, {"group": "MyGroup2",
 ---   "pattern": "FIXME", "priority": 10, "id": 2}]
---- >vim
+--- < >vim
 ---   :let m = getmatches()
 ---   :call clearmatches()
 ---   :echo getmatches()
---- >
+--- < >
 ---   []
---- >vim
+--- < >vim
 ---   :call setmatches(m)
 ---   :echo getmatches()
---- >
+--- < >
 ---   [{"group": "MyGroup1", "pattern": "TODO",
 ---   "priority": 10, "id": 1}, {"group": "MyGroup2",
 ---   "pattern": "FIXME", "priority": 10, "id": 2}]
---- >vim
+--- < >vim
 ---   :unlet m
 --- <
+---
 --- @param win? any
 --- @return any
 function vim.fn.getmatches(win) end
@@ -3503,11 +3588,13 @@ function vim.fn.getmatches(win) end
 --- @return any
 function vim.fn.getmousepos() end
 
+--- Return a Number which is the process ID of the Vim process.
 --- This is a unique number, until Vim exits.
 ---
 --- @return integer
 function vim.fn.getpid() end
 
+--- Get the position for String {expr}.  For possible values of
 --- {expr} see |line()|.  For getting the cursor position see
 --- |getcurpos()|.
 --- The result is a |List| with four numbers:
@@ -3641,6 +3728,7 @@ function vim.fn.getpos(expr) end
 ---   :echo getqflist({'nr': 2, 'title': 1})
 ---   :echo getqflist({'lines' : ["F1:10:L10"]})
 --- <
+---
 --- @param what? any
 --- @return any
 function vim.fn.getqflist(what) end
@@ -3757,6 +3845,7 @@ function vim.fn.getregtype(regname) end
 ---   :echo getscriptinfo({'name': 'myscript'})
 ---   :echo getscriptinfo({'sid': 15}).variables
 --- <
+---
 --- @param opts? table
 --- @return any
 function vim.fn.getscriptinfo(opts) end
@@ -3822,8 +3911,8 @@ function vim.fn.gettabvar(tabnr, varname, def) end
 --- <
 --- To obtain all window-local variables use: >
 ---   gettabwinvar({tabnr}, {winnr}, '&')
----
---- <Can also be used as a |method|: >
+--- <
+--- Can also be used as a |method|: >
 ---   GetTabnr()->gettabwinvar(winnr, varname)
 ---
 --- @param tabnr integer
@@ -3862,7 +3951,7 @@ function vim.fn.gettabwinvar(tabnr, winnr, varname, def) end
 ---
 --- Can also be used as a |method|: >
 ---   GetWinnr()->gettagstack()
----
+--- <
 ---
 --- @param winnr? integer
 --- @return any
@@ -3878,7 +3967,6 @@ function vim.fn.gettagstack(winnr) end
 --- xgettext does not understand escaping in single quoted
 --- strings.
 ---
----
 --- @param text any
 --- @return any
 function vim.fn.gettext(text) end
@@ -3945,10 +4033,12 @@ function vim.fn.getwininfo(winid) end
 --- Can also be used as a |method|: >
 ---   GetTimeout()->getwinpos()
 --- <
+---
 --- @param timeout? integer
 --- @return any
 function vim.fn.getwinpos(timeout) end
 
+--- The result is a Number, which is the X coordinate in pixels of
 --- the left hand side of the GUI Vim window.  The result will be
 --- -1 if the information is not available.
 --- The value can be used with `:winpos`.
@@ -3956,6 +4046,7 @@ function vim.fn.getwinpos(timeout) end
 --- @return integer
 function vim.fn.getwinposx() end
 
+--- The result is a Number, which is the Y coordinate in pixels of
 --- the top of the GUI Vim window.  The result will be -1 if the
 --- information is not available.
 --- The value can be used with `:winpos`.
@@ -3971,6 +4062,7 @@ function vim.fn.getwinposy() end
 --- <Can also be used as a |method|: >
 ---   GetWinnr()->getwinvar(varname)
 --- <
+---
 --- @param winnr integer
 --- @param varname string
 --- @param def? any
@@ -4035,6 +4127,8 @@ function vim.fn.glob(expr, nosuf, list, alllinks) end
 ---
 --- Can also be used as a |method|: >
 ---   GetExpr()->glob2regpat()
+--- <
+---
 --- @param string string
 --- @return any
 function vim.fn.glob2regpat(string) end
@@ -4077,6 +4171,7 @@ function vim.fn.glob2regpat(string) end
 --- second argument: >
 ---   GetExpr()->globpath(&rtp)
 --- <
+---
 --- @param path string
 --- @param expr any
 --- @param nosuf? boolean
@@ -4085,6 +4180,7 @@ function vim.fn.glob2regpat(string) end
 --- @return any
 function vim.fn.globpath(path, expr, nosuf, list, allinks) end
 
+--- Returns 1 if {feature} is supported, 0 otherwise.  The
 --- {feature} argument is a feature name like "nvim-0.2.1" or
 --- "win32", see below.  See also |exists()|.
 ---
@@ -4141,7 +4237,7 @@ function vim.fn.globpath(path, expr, nosuf, list, allinks) end
 --- <4.  Vim version. For example the "patch-7.4.237" feature means
 ---     that Nvim is Vim-compatible to version 7.4.237 or later. >
 ---   :if has("patch-7.4.237")
----
+--- <
 ---
 --- @param feature any
 --- @return 0|1
@@ -4224,11 +4320,17 @@ function vim.fn.hasmapto(what, mode, abbr) end
 
 --- @deprecated
 --- Obsolete name for |hlID()|.
-function vim.fn.highlightID(...) end
+---
+--- @param name string
+--- @return any
+function vim.fn.highlightID(name) end
 
 --- @deprecated
 --- Obsolete name for |hlexists()|.
-function vim.fn.highlight_exists(...) end
+---
+--- @param name string
+--- @return any
+function vim.fn.highlight_exists(name) end
 
 --- Add the String {item} to the history {history} which can be
 --- one of:          *hist-names*
@@ -4330,10 +4432,12 @@ function vim.fn.histget(history, index) end
 --- <Can also be used as a |method|: >
 ---   GetHistory()->histnr()
 --- <
+---
 --- @param history any
 --- @return integer
 function vim.fn.histnr(history) end
 
+--- The result is a Number, which is the ID of the highlight group
 --- with name {name}.  When the highlight group doesn't exist,
 --- zero is returned.
 --- This can be used to retrieve information about the highlight
@@ -4357,6 +4461,7 @@ function vim.fn.hlID(name) end
 --- Can also be used as a |method|: >
 ---   GetName()->hlexists()
 --- <
+---
 --- @param name string
 --- @return 0|1
 function vim.fn.hlexists(name) end
@@ -4382,6 +4487,7 @@ function vim.fn.hostname() end
 --- Can also be used as a |method|: >
 ---   GetText()->iconv('latin1', 'utf-8')
 --- <
+---
 --- @param string string
 --- @param from any
 --- @param to any
@@ -4500,6 +4606,13 @@ function vim.fn.index(object, expr, start, ic) end
 --- @return any
 function vim.fn.indexof(object, expr, opts) end
 
+---
+--- @param prompt any
+--- @param text? any
+--- @param completion? any
+--- @return any
+function vim.fn.input(prompt, text, completion) end
+
 --- The result is a String, which is whatever the user typed on
 --- the command-line.  The {prompt} argument is either a prompt
 --- string, or a blank string (for no prompt).  A '\n' can be used
@@ -4618,6 +4731,9 @@ function vim.fn.input(opts) end
 
 --- @deprecated
 --- Use |input()| instead.
+---
+--- @param ... any
+--- @return any
 function vim.fn.inputdialog(...) end
 
 --- {textlist} must be a |List| of strings.  This |List| is
@@ -4804,6 +4920,9 @@ function vim.fn.items(dict) end
 
 --- @deprecated
 --- Obsolete name for |chanclose()|
+---
+--- @param ... any
+--- @return any
 function vim.fn.jobclose(...) end
 
 --- Return the PID (process id) of |job-id| {job}.
@@ -4824,6 +4943,9 @@ function vim.fn.jobresize(job, width, height) end
 
 --- @deprecated
 --- Obsolete name for |chansend()|
+---
+--- @param ... any
+--- @return any
 function vim.fn.jobsend(...) end
 
 --- Note: Prefer |vim.system()| in Lua.
@@ -5030,6 +5152,7 @@ function vim.fn.keys(dict) end
 ---
 --- Can also be used as a |method|: >
 ---   "\<C-Home>"->keytrans()
+--- <
 ---
 --- @param string string
 --- @return any
@@ -5037,7 +5160,9 @@ function vim.fn.keytrans(string) end
 
 --- @deprecated
 --- Obsolete name for bufnr("$").
-function vim.fn.last_buffer_nr(...) end
+---
+--- @return any
+function vim.fn.last_buffer_nr() end
 
 --- When {expr} is a String or a Number the length in bytes is
 --- used, as with |strlen()|.
@@ -5050,6 +5175,7 @@ function vim.fn.last_buffer_nr(...) end
 ---
 --- Can also be used as a |method|: >
 ---   mylist->len()
+--- <
 ---
 --- @param expr any
 --- @return any
@@ -5100,6 +5226,7 @@ function vim.fn.len(expr) end
 --- third argument: >
 ---   GetValue()->libcall("libc.so", "getenv")
 --- <
+---
 --- @param libname string
 --- @param funcname string
 --- @param argument any
@@ -5117,6 +5244,7 @@ function vim.fn.libcall(libname, funcname, argument) end
 --- third argument: >
 ---   GetValue()->libcallnr("libc.so", "printf")
 --- <
+---
 --- @param libname string
 --- @param funcname string
 --- @param argument any
@@ -5236,7 +5364,6 @@ function vim.fn.list2str(list, utf8) end
 --- Return the current time, measured as seconds since 1st Jan
 --- 1970.  See also |strftime()|, |strptime()| and |getftime()|.
 ---
----
 --- @return any
 function vim.fn.localtime() end
 
@@ -5273,17 +5400,6 @@ function vim.fn.log(expr) end
 --- @return any
 function vim.fn.log10(expr) end
 
---- Evaluate Lua expression {expr} and return its result converted
---- to Vim data structures. See |lua-eval| for more details.
----
---- Can also be used as a |method|: >
----   GetExpr()->luaeval()
----
---- @param expr any
---- @param expr1? any
---- @return any
-function vim.fn.luaeval(expr, expr1) end
-
 --- {expr1} must be a |List|, |Blob| or |Dictionary|.
 --- Replace each item in {expr1} with the result of evaluating
 --- {expr2}.  For a |Blob| each byte is replaced.
@@ -5332,7 +5448,7 @@ function vim.fn.luaeval(expr, expr1) end
 ---
 --- Can also be used as a |method|: >