fix(docs): missing `@returns` desc in _meta/api.lua #30673

3 files changed, 267 insertions, 98 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 0d4f2c7da0..072f50e1a2 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -27,7 +27,9 @@ function vim.api.nvim__buf_stats(buffer) end
 --- @param index integer Completion candidate index
 --- @param opts vim.api.keyset.complete_set Optional parameters.
 ---             • info: (string) info text.
---- @return table<string,any>
+--- @return table<string,any> # Dict containing these keys:
+--- - winid: (number) floating window id
+--- - bufnr: (number) buffer id in floating window
 function vim.api.nvim__complete_set(index, opts) end
 
 --- @private
@@ -40,7 +42,7 @@ function vim.api.nvim__get_lib_dir() end
 --- @param pat any[] pattern of files to search for
 --- @param all boolean whether to return all matches or only the first
 --- @param opts vim.api.keyset.runtime is_lua: only search Lua subdirs
---- @return string[]
+--- @return string[] # list of absolute paths to the found files
 function vim.api.nvim__get_runtime(pat, all, opts) end
 
 --- @private
@@ -50,7 +52,7 @@ function vim.api.nvim__get_runtime(pat, all, opts) end
 --- in plugins.
 ---
 --- @param obj any Object to return.
---- @return any
+--- @return any # its argument.
 function vim.api.nvim__id(obj) end
 
 --- @private
@@ -60,7 +62,7 @@ function vim.api.nvim__id(obj) end
 --- in plugins.
 ---
 --- @param arr any[] Array to return.
---- @return any[]
+--- @return any[] # its argument.
 function vim.api.nvim__id_array(arr) end
 
 --- @private
@@ -70,7 +72,7 @@ function vim.api.nvim__id_array(arr) end
 --- in plugins.
 ---
 --- @param dct table<string,any> Dict to return.
---- @return table<string,any>
+--- @return table<string,any> # its argument.
 function vim.api.nvim__id_dict(dct) end
 
 --- @private
@@ -80,7 +82,7 @@ function vim.api.nvim__id_dict(dct) end
 --- in plugins.
 ---
 --- @param flt number Value to return.
---- @return number
+--- @return number # its argument.
 function vim.api.nvim__id_float(flt) end
 
 --- @private
@@ -105,7 +107,7 @@ function vim.api.nvim__invalidate_glyph_cache() end
 --- Get the properties for namespace
 ---
 --- @param ns_id integer Namespace
---- @return vim.api.keyset.ns_opts
+--- @return vim.api.keyset.ns_opts # Map defining the namespace properties, see |nvim__ns_set()|
 function vim.api.nvim__ns_get(ns_id) end
 
 --- @private
@@ -156,7 +158,7 @@ function vim.api.nvim__screenshot(path) end
 --- @private
 --- Gets internal stats.
 ---
---- @return table<string,any>
+--- @return table<string,any> # Map of various internal stats.
 function vim.api.nvim__stats() end
 
 --- @private
@@ -192,7 +194,7 @@ function vim.api.nvim__unpack(str) end
 --- @param col_start integer Start of (byte-indexed) column range to highlight
 --- @param col_end integer End of (byte-indexed) column range to highlight, or -1 to
 ---                highlight to end of line
---- @return integer
+--- @return integer # The ns_id that was used
 function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end
 
 --- Activates buffer-update events on a channel, or as Lua callbacks.
@@ -265,7 +267,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
 ---               region, as args to `on_lines`.
 ---             • preview: also attach to command preview (i.e. 'inccommand')
 ---               events.
---- @return boolean
+--- @return boolean # False if attach failed (invalid parameter, or buffer isn't loaded);
+--- otherwise True. TODO: LUA_API_NO_EVAL
 function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end
 
 --- Call a function with buffer as temporary current buffer.
@@ -283,7 +286,7 @@ function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param fun function Function to call inside the buffer (currently Lua callable
 ---            only)
---- @return any
+--- @return any # Return value of function.
 function vim.api.nvim_buf_call(buffer, fun) end
 
 --- @deprecated
@@ -320,7 +323,7 @@ function vim.api.nvim_buf_create_user_command(buffer, name, command, opts) end
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param ns_id integer Namespace id from `nvim_create_namespace()`
 --- @param id integer Extmark id
---- @return boolean
+--- @return boolean # true if the extmark was found, else false
 function vim.api.nvim_buf_del_extmark(buffer, ns_id, id) end
 
 --- Unmaps a buffer-local `mapping` for the given mode.
@@ -341,7 +344,7 @@ function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end
 --- @see `nvim_del_mark()`
 --- @param buffer integer Buffer to set the mark on
 --- @param name string Mark name
---- @return boolean
+--- @return boolean # true if the mark was deleted, else false.
 function vim.api.nvim_buf_del_mark(buffer, name) end
 
 --- Delete a buffer-local user-defined command.
@@ -370,14 +373,14 @@ function vim.api.nvim_buf_delete(buffer, opts) end
 --- Gets a changed tick of a buffer
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @return integer
+--- @return integer # `b:changedtick` value.
 function vim.api.nvim_buf_get_changedtick(buffer) end
 
 --- Gets a map of buffer-local `user-commands`.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param opts vim.api.keyset.get_commands Optional parameters. Currently not used.
---- @return table<string,any>
+--- @return table<string,any> # Map of maps describing commands.
 function vim.api.nvim_buf_get_commands(buffer, opts) end
 
 --- Gets the position (0-indexed) of an `extmark`.
@@ -389,7 +392,8 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end
 ---             • details: Whether to include the details dict
 ---             • hl_name: Whether to include highlight group name instead of
 ---               id, true if omitted
---- @return vim.api.keyset.get_extmark_item_by_id
+--- @return vim.api.keyset.get_extmark_item_by_id # 0-indexed (row, col) tuple or empty list () if extmark id was
+--- absent
 function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 
 --- Gets `extmarks` in "traversal order" from a `charwise` region defined by
@@ -449,14 +453,15 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 ---               their start position is less than `start`
 ---             • type: Filter marks by type: "highlight", "sign", "virt_text"
 ---               and "virt_lines"
---- @return vim.api.keyset.get_extmark_item[]
+--- @return vim.api.keyset.get_extmark_item[] # List of `[extmark_id, row, col]` tuples in "traversal order".
 function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end
 
 --- Gets a list of buffer-local `mapping` definitions.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param mode string Mode short-name ("n", "i", "v", ...)
---- @return vim.api.keyset.keymap[]
+--- @return vim.api.keyset.keymap[] # Array of |maparg()|-like dictionaries describing mappings.
+--- The "buffer" key holds the associated buffer handle.
 function vim.api.nvim_buf_get_keymap(buffer, mode) end
 
 --- Gets a line-range from the buffer.
@@ -472,7 +477,7 @@ function vim.api.nvim_buf_get_keymap(buffer, mode) end
 --- @param start integer First line index
 --- @param end_ integer Last line index, exclusive
 --- @param strict_indexing boolean Whether out-of-bounds should be an error.
---- @return string[]
+--- @return string[] # Array of lines, or empty array for unloaded buffer.
 function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end
 
 --- Returns a `(row,col)` tuple representing the position of the named mark.
@@ -485,13 +490,14 @@ function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end
 --- @see `nvim_buf_del_mark()`
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param name string Mark name
---- @return integer[]
+--- @return integer[] # (row, col) tuple, (0, 0) if the mark is not set, or is an
+--- uppercase/file mark set in another buffer.
 function vim.api.nvim_buf_get_mark(buffer, name) end
 
 --- Gets the full file name for the buffer
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @return string
+--- @return string # Buffer name
 function vim.api.nvim_buf_get_name(buffer) end
 
 --- @deprecated
@@ -511,7 +517,7 @@ function vim.api.nvim_buf_get_number(buffer) end
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param index integer Line index
---- @return integer
+--- @return integer # Integer byte offset, or -1 for unloaded buffer.
 function vim.api.nvim_buf_get_offset(buffer, index) end
 
 --- @deprecated
@@ -536,21 +542,21 @@ function vim.api.nvim_buf_get_option(buffer, name) end
 --- @param end_row integer Last line index, inclusive
 --- @param end_col integer Ending column (byte offset) on last line, exclusive
 --- @param opts vim.api.keyset.empty Optional parameters. Currently unused.
---- @return string[]
+--- @return string[] # Array of lines, or empty array for unloaded buffer.
 function vim.api.nvim_buf_get_text(buffer, start_row, start_col, end_row, end_col, opts) end
 
 --- Gets a buffer-scoped (b:) variable.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param name string Variable name
---- @return any
+--- @return any # Variable value
 function vim.api.nvim_buf_get_var(buffer, name) end
 
 --- Checks if a buffer is valid and loaded. See `api-buffer` for more info
 --- about unloaded buffers.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @return boolean
+--- @return boolean # true if the buffer is valid and loaded, false otherwise.
 function vim.api.nvim_buf_is_loaded(buffer) end
 
 --- Checks if a buffer is valid.
@@ -560,13 +566,13 @@ function vim.api.nvim_buf_is_loaded(buffer) end
 ---   for more info about unloaded buffers.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @return boolean
+--- @return boolean # true if the buffer is valid, false otherwise.
 function vim.api.nvim_buf_is_valid(buffer) end
 
 --- Returns the number of lines in the given buffer.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
---- @return integer
+--- @return integer # Line count, or 0 for unloaded buffer. |api-buffer|
 function vim.api.nvim_buf_line_count(buffer) end
 
 --- Creates or updates an `extmark`.
@@ -692,7 +698,7 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---             • url: A URL to associate with this extmark. In the TUI, the
 ---               OSC 8 control sequence is used to generate a clickable
 ---               hyperlink to this URL.
---- @return integer
+--- @return integer # Id of the created/updated extmark
 function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
 
 --- Sets a buffer-local `mapping` for the given mode.
@@ -740,7 +746,7 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac
 --- @param line integer Line number
 --- @param col integer Column/row number
 --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
---- @return boolean
+--- @return boolean # true if the mark was set, else false.
 function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end
 
 --- Sets the full file name for a buffer, like `:file_f`
@@ -805,7 +811,7 @@ function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) e
 --- @param dict any Dict, or String evaluating to a Vimscript `self` dict
 --- @param fn string Name of the function defined on the Vimscript dict
 --- @param args any[] Function arguments packed in an Array
---- @return any
+--- @return any # Result of the function call
 function vim.api.nvim_call_dict_function(dict, fn, args) end
 
 --- Calls a Vimscript function with the given arguments.
@@ -814,7 +820,7 @@ function vim.api.nvim_call_dict_function(dict, fn, args) end
 ---
 --- @param fn string Function to call
 --- @param args any[] Function arguments packed in an Array
---- @return any
+--- @return any # Result of the function call
 function vim.api.nvim_call_function(fn, args) end
 
 --- Send data to channel `id`. For a job, it writes it to the stdin of the
@@ -878,7 +884,7 @@ function vim.api.nvim_clear_autocmds(opts) end
 --- @param opts vim.api.keyset.cmd_opts Optional parameters.
 ---             • output: (boolean, default false) Whether to return command
 ---               output.
---- @return string
+--- @return string # Command output (non-error, non-shell |:!|) if `output` is true, else empty string.
 function vim.api.nvim_cmd(cmd, opts) end
 
 --- Executes an Ex command.
@@ -916,7 +922,7 @@ function vim.api.nvim_command_output(command) end
 --- @param opts vim.api.keyset.create_augroup Dict Parameters
 ---             • clear (bool) optional: defaults to true. Clear existing
 ---               commands if the group already exists `autocmd-groups`.
---- @return integer
+--- @return integer # Integer id of the created group.
 function vim.api.nvim_create_augroup(name, opts) end
 
 --- Creates an `autocommand` event handler, defined by `callback` (Lua
@@ -985,7 +991,7 @@ function vim.api.nvim_create_augroup(name, opts) end
 ---               autocommand only once `autocmd-once`.
 ---             • nested (boolean) optional: defaults to false. Run nested
 ---               autocommands `autocmd-nested`.
---- @return integer
+--- @return integer # Autocommand id (number)
 function vim.api.nvim_create_autocmd(event, opts) end
 
 --- Creates a new, empty, unnamed buffer.
@@ -995,7 +1001,7 @@ function vim.api.nvim_create_autocmd(event, opts) end
 --- @param scratch boolean Creates a "throwaway" `scratch-buffer` for temporary work
 ---                (always 'nomodified'). Also sets 'nomodeline' on the
 ---                buffer.
---- @return integer
+--- @return integer # Buffer handle, or 0 on error
 function vim.api.nvim_create_buf(listed, scratch) end
 
 --- Creates a new namespace or gets an existing one.               *namespace*
@@ -1008,7 +1014,7 @@ function vim.api.nvim_create_buf(listed, scratch) end
 --- new, anonymous namespace is created.
 ---
 --- @param name string Namespace name or empty string
---- @return integer
+--- @return integer # Namespace id
 function vim.api.nvim_create_namespace(name) end
 
 --- Creates a global `user-commands` command.
@@ -1114,7 +1120,7 @@ function vim.api.nvim_del_keymap(mode, lhs) end
 --- @see `nvim_buf_del_mark()`
 --- @see `nvim_get_mark()`
 --- @param name string Mark name
---- @return boolean
+--- @return boolean # true if the mark was deleted, else false.
 function vim.api.nvim_del_mark(name) end
 
 --- Delete a user-defined command.
@@ -1159,7 +1165,7 @@ function vim.api.nvim_err_writeln(str) end
 --- On execution error: fails with Vimscript error, updates v:errmsg.
 ---
 --- @param expr string Vimscript expression string
---- @return any
+--- @return any # Evaluation result or expanded object
 function vim.api.nvim_eval(expr) end
 
 --- Evaluates statusline string.
@@ -1179,7 +1185,14 @@ function vim.api.nvim_eval(expr) end
 ---               exclusive with {use_winbar}.
 ---             • use_statuscol_lnum: (number) Evaluate statuscolumn for this
 ---               line number instead of statusline.
---- @return table<string,any>
+--- @return table<string,any> # Dict containing statusline information, with these keys:
+--- - str: (string) Characters that will be displayed on the statusline.
+--- - width: (number) Display width of the statusline.
+--- - highlights: Array containing highlight information of the statusline. Only included when
+---               the "highlights" key in {opts} is true. Each element of the array is a
+---               |Dict| with these keys:
+---     - start: (number) Byte index (0-based) of first character that uses the highlight.
+---     - group: (string) Name of highlight group.
 function vim.api.nvim_eval_statusline(str, opts) end
 
 --- @deprecated
@@ -1204,7 +1217,8 @@ function vim.api.nvim_exec(src, output) end
 --- @param opts vim.api.keyset.exec_opts Optional parameters.
 ---             • output: (boolean, default false) Whether to capture and
 ---               return all (non-error, non-shell `:!`) output.
---- @return table<string,any>
+--- @return table<string,any> # Dict containing information about execution, with these keys:
+--- - output: (string|nil) Output if `opts.output` is true.
 function vim.api.nvim_exec2(src, opts) end
 
 --- Execute all autocommands for {event} that match the corresponding {opts}
@@ -1257,7 +1271,7 @@ function vim.api.nvim_feedkeys(keys, mode, escape_ks) end
 --- detailed at `nvim_get_option_info2()`.
 ---
 --- @see `nvim_get_commands()`
---- @return table<string,any>
+--- @return table<string,any> # dict of all options
 function vim.api.nvim_get_all_options_info() end
 
 --- Get all autocommands that match the corresponding {opts}.
@@ -1291,13 +1305,44 @@ function vim.api.nvim_get_all_options_info() end
 ---             • buffer: Buffer number or list of buffer numbers for buffer
 ---               local autocommands `autocmd-buflocal`. Cannot be used with
 ---               {pattern}
---- @return vim.api.keyset.get_autocmds.ret[]
+--- @return vim.api.keyset.get_autocmds.ret[] # Array of autocommands matching the criteria, with each item
+--- containing the following fields:
+--- - id (number): the autocommand id (only when defined with the API).
+--- - group (integer): the autocommand group id.
+--- - group_name (string): the autocommand group name.
+--- - desc (string): the autocommand description.
+--- - event (string): the autocommand event.
+--- - command (string): the autocommand command. Note: this will be empty if a callback is set.
+--- - callback (function|string|nil): Lua function or name of a Vim script function
+---   which is executed when this autocommand is triggered.
+--- - once (boolean): whether the autocommand is only run once.
+--- - pattern (string): the autocommand pattern.
+---   If the autocommand is buffer local |autocmd-buffer-local|:
+--- - buflocal (boolean): true if the autocommand is buffer local.
+--- - buffer (number): the buffer number.
 function vim.api.nvim_get_autocmds(opts) end
 
 --- Gets information about a channel.
 ---
 --- @param chan integer channel_id, or 0 for current channel
---- @return table<string,any>
+--- @return table<string,any> # Channel info dict with these keys:
+--- - "id"       Channel id.
+--- - "argv"     (optional) Job arguments list.
+--- - "stream"   Stream underlying the channel.
+---      - "stdio"      stdin and stdout of this Nvim instance
+---      - "stderr"     stderr of this Nvim instance
+---      - "socket"     TCP/IP socket or named pipe
+---      - "job"        Job with communication over its stdio.
+--- -  "mode"    How data received on the channel is interpreted.
+---      - "bytes"      Send and receive raw bytes.
+---      - "terminal"   |terminal| instance interprets ASCII sequences.
+---      - "rpc"        |RPC| communication on the channel is active.
+--- -  "pty"     (optional) Name of pseudoterminal. On a POSIX system this is a device path like
+---              "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
+---              for conpty on Windows).
+--- -  "buffer"  (optional) Buffer connected to |terminal| instance.
+--- -  "client"  (optional) Info about the peer (client on the other end of the RPC channel),
+---              which it provided via |nvim_set_client_info()|.
 function vim.api.nvim_get_chan_info(chan) end
 
 --- Returns the 24-bit RGB value of a `nvim_get_color_map()` color name or
@@ -1312,7 +1357,7 @@ function vim.api.nvim_get_chan_info(chan) end
 ---
 ---
 --- @param name string Color name or "#rrggbb" string
---- @return integer
+--- @return integer # 24-bit RGB value, or -1 for invalid argument.
 function vim.api.nvim_get_color_by_name(name) end
 
 --- Returns a map of color names and RGB values.
@@ -1320,7 +1365,7 @@ function vim.api.nvim_get_color_by_name(name) end
 --- Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values
 --- (e.g. 65535).
 ---
---- @return table<string,integer>
+--- @return table<string,integer> # Map of color names and RGB values.
 function vim.api.nvim_get_color_map() end
 
 --- Gets a map of global (non-buffer-local) Ex commands.
@@ -1329,7 +1374,7 @@ function vim.api.nvim_get_color_map() end
 ---
 --- @see `nvim_get_all_options_info()`
 --- @param opts vim.api.keyset.get_commands Optional parameters. Currently only supports {"builtin":false}
---- @return table<string,any>
+--- @return table<string,any> # Map of maps describing commands.
 function vim.api.nvim_get_commands(opts) end
 
 --- Gets a map of the current editor state.
@@ -1337,27 +1382,27 @@ function vim.api.nvim_get_commands(opts) end
 --- @param opts vim.api.keyset.context Optional parameters.
 ---             • types: List of `context-types` ("regs", "jumps", "bufs",
 ---               "gvars", …) to gather, or empty for "all".
---- @return table<string,any>
+--- @return table<string,any> # map of global |context|.
 function vim.api.nvim_get_context(opts) end
 
 --- Gets the current buffer.
 ---
---- @return integer
+--- @return integer # Buffer handle
 function vim.api.nvim_get_current_buf() end
 
 --- Gets the current line.
 ---
---- @return string
+--- @return string # Current line string
 function vim.api.nvim_get_current_line() end
 
 --- Gets the current tabpage.
 ---
---- @return integer
+--- @return integer # Tabpage handle
 function vim.api.nvim_get_current_tabpage() end
 
 --- Gets the current window.
 ---
---- @return integer
+--- @return integer # Window handle
 function vim.api.nvim_get_current_win() end
 
 --- Gets all or specific highlight groups in a namespace.
@@ -1376,7 +1421,8 @@ function vim.api.nvim_get_current_win() end
 ---               of effective definition `:hi-link`.
 ---             • create: (boolean, default true) When highlight group doesn't
 ---               exist create it.
---- @return vim.api.keyset.get_hl_info
+--- @return vim.api.keyset.get_hl_info # Highlight groups as a map from group name to a highlight definition map as in |nvim_set_hl()|,
+--- or only a single highlight definition map if requested by name or id.
 function vim.api.nvim_get_hl(ns_id, opts) end
 
 --- @deprecated
@@ -1408,13 +1454,14 @@ function vim.api.nvim_get_hl_id_by_name(name) end
 ---               highlight namespace. A value of -1 is returned when
 ---               `nvim_win_set_hl_ns()` has not been called for the window
 ---               (or was called with a namespace of -1).
---- @return integer
+--- @return integer # Namespace id, or -1
 function vim.api.nvim_get_hl_ns(opts) end
 
 --- Gets a list of global (non-buffer-local) `mapping` definitions.
 ---
 --- @param mode string Mode short-name ("n", "i", "v", ...)
---- @return vim.api.keyset.keymap[]
+--- @return vim.api.keyset.keymap[] # Array of |maparg()|-like dictionaries describing mappings.
+--- The "buffer" key is always zero.
 function vim.api.nvim_get_keymap(mode) end
 
 --- Returns a `(row, col, buffer, buffername)` tuple representing the position
@@ -1430,18 +1477,19 @@ function vim.api.nvim_get_keymap(mode) end
 --- @see `nvim_del_mark()`
 --- @param name string Mark name
 --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
---- @return vim.api.keyset.get_mark
+--- @return vim.api.keyset.get_mark # 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is
+--- not set.
 function vim.api.nvim_get_mark(name, opts) end
 
 --- Gets the current mode. `mode()` "blocking" is true if Nvim is waiting for
 --- input.
 ---
---- @return vim.api.keyset.get_mode
+--- @return vim.api.keyset.get_mode # Dict { "mode": String, "blocking": Boolean }
 function vim.api.nvim_get_mode() end
 
 --- Gets existing, non-anonymous `namespace`s.
 ---
---- @return table<string,integer>
+--- @return table<string,integer> # dict that maps from names to namespace ids.
 function vim.api.nvim_get_namespaces() end
 
 --- @deprecated
@@ -1482,7 +1530,7 @@ function vim.api.nvim_get_option_info(name) end
 ---             • win: `window-ID`. Used for getting window local options.
 ---             • buf: Buffer number. Used for getting buffer local options.
 ---               Implies {scope} is "local".
---- @return vim.api.keyset.get_option_info
+--- @return vim.api.keyset.get_option_info # Option Information
 function vim.api.nvim_get_option_info2(name, opts) end
 
 --- Gets the value of an option. The behavior of this function matches that of
@@ -1501,19 +1549,19 @@ function vim.api.nvim_get_option_info2(name, opts) end
 ---               specific filetype. Cannot be used with any other option.
 ---               Note: this will trigger `ftplugin` and all `FileType`
 ---               autocommands for the corresponding filetype.
---- @return any
+--- @return any # Option value
 function vim.api.nvim_get_option_value(name, opts) end
 
 --- Gets info describing process `pid`.
 ---
 --- @param pid integer
---- @return any
+--- @return any # Map of process properties, or NIL if process not found.
 function vim.api.nvim_get_proc(pid) end
 
 --- Gets the immediate children of process `pid`.
 ---
 --- @param pid integer
---- @return any[]
+--- @return any[] # Array of child process ids, empty if process not found.
 function vim.api.nvim_get_proc_children(pid) end
 
 --- Finds files in runtime directories, in 'runtimepath' order.
@@ -1527,19 +1575,19 @@ function vim.api.nvim_get_proc_children(pid) end
 ---
 --- @param name string pattern of files to search for
 --- @param all boolean whether to return all matches or only the first
---- @return string[]
+--- @return string[] # list of absolute paths to the found files
 function vim.api.nvim_get_runtime_file(name, all) end
 
 --- Gets a global (g:) variable.
 ---
 --- @param name string Variable name
---- @return any
+--- @return any # Variable value
 function vim.api.nvim_get_var(name) end
 
 --- Gets a v: variable.
 ---
 --- @param name string Variable name
---- @return any
+--- @return any # Variable value
 function vim.api.nvim_get_vvar(name) end
 
 --- Queues raw user-input. Unlike `nvim_feedkeys()`, this uses a low-level
@@ -1558,7 +1606,8 @@ function vim.api.nvim_get_vvar(name) end
 ---   `<LeftMouse><col,row>` is deprecated since `api-level` 6.
 ---
 --- @param keys string to be typed
---- @return integer
+--- @return integer # Number of bytes actually written (can be fewer than
+--- requested if the buffer becomes full).
 function vim.api.nvim_input(keys) end
 
 --- Send mouse event from GUI.
@@ -1592,32 +1641,38 @@ function vim.api.nvim_input_mouse(button, action, modifier, grid, row, col) end
 --- Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use
 --- `nvim_buf_is_loaded()` to check if a buffer is loaded.
 ---
---- @return integer[]
+--- @return integer[] # List of buffer handles
 function vim.api.nvim_list_bufs() end
 
 --- Get information about all open channels.
 ---
---- @return any[]
+--- @return any[] # Array of Dictionaries, each describing a channel with
+--- the format specified at |nvim_get_chan_info()|.
 function vim.api.nvim_list_chans() end
 
 --- Gets the paths contained in `runtime-search-path`.
 ---
---- @return string[]
+--- @return string[] # List of paths
 function vim.api.nvim_list_runtime_paths() end
 
 --- Gets the current list of tabpage handles.
 ---
---- @return integer[]
+--- @return integer[] # List of tabpage handles
 function vim.api.nvim_list_tabpages() end
 
 --- Gets a list of dictionaries representing attached UIs.
 ---
---- @return any[]
+--- @return any[] # Array of UI dictionaries, each with these keys:
+--- - "height"  Requested height of the UI
+--- - "width"   Requested width of the UI
+--- - "rgb"     true if the UI uses RGB colors (false implies |cterm-colors|)
+--- - "ext_..." Requested UI extensions, see |ui-option|
+--- - "chan"    |channel-id| of remote UI
 function vim.api.nvim_list_uis() end
 
 --- Gets the current list of window handles.
 ---
---- @return integer[]
+--- @return integer[] # List of window handles
 function vim.api.nvim_list_wins() end
 
 --- Sets the current editor state from the given `context` map.
@@ -1660,7 +1715,7 @@ function vim.api.nvim_notify(msg, log_level, opts) end
 ---               possible to call `nvim_chan_send()` directly in the callback
 ---               however. `["input", term, bufnr, data]`
 ---             • force_crlf: (boolean, default true) Convert "\n" to "\r\n".
---- @return integer
+--- @return integer # Channel id, or 0 on error
 function vim.api.nvim_open_term(buffer, opts) end
 
 --- Opens a new split window, or a floating window if `relative` is specified,
@@ -1845,7 +1900,7 @@ function vim.api.nvim_open_term(buffer, opts) end
 ---               • hide: If true the floating window will be hidden.
 ---               • vertical: Split vertically `:vertical`.
 ---               • split: Split direction: "left", "right", "above", "below".
---- @return integer
+--- @return integer # Window handle, or 0 on error
 function vim.api.nvim_open_win(buffer, enter, config) end
 
 --- Writes a message to the Vim output buffer. Does not append "\n", the
@@ -1860,7 +1915,56 @@ function vim.api.nvim_out_write(str) end
 ---
 --- @param str string Command line string to parse. Cannot contain "\n".
 --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
---- @return vim.api.keyset.parse_cmd
+--- @return vim.api.keyset.parse_cmd # Dict containing command information, with these keys:
+--- - cmd: (string) Command name.
+--- - range: (array) (optional) Command range ([<line1>] [<line2>]).
+---                  Omitted if command doesn't accept a range.
+---                  Otherwise, has no elements if no range was specified, one element if
+---                  only a single range item was specified, or two elements if both range
+---                  items were specified.
+--- - count: (number) (optional) Command [<count>].
+---                   Omitted if command cannot take a count.
+--- - reg: (string) (optional) Command [<register>].
+---                 Omitted if command cannot take a register.
+--- - bang: (boolean) Whether command contains a [<bang>] (!) modifier.
+--- - args: (array) Command arguments.
+--- - addr: (string) Value of |:command-addr|. Uses short name or "line" for -addr=lines.
+--- - nargs: (string) Value of |:command-nargs|.
+--- - nextcmd: (string) Next command if there are multiple commands separated by a |:bar|.
+---                     Empty if there isn't a next command.
+--- - magic: (dict) Which characters have special meaning in the command arguments.
+---     - file: (boolean) The command expands filenames. Which means characters such as "%",
+---                       "#" and wildcards are expanded.
+---     - bar: (boolean) The "|" character is treated as a command separator and the double
+---                      quote character (") is treated as the start of a comment.
+--- - mods: (dict) |:command-modifiers|.
+---     - filter: (dict) |:filter|.
+---         - pattern: (string) Filter pattern. Empty string if there is no filter.
+---         - force: (boolean) Whether filter is inverted or not.
+---     - silent: (boolean) |:silent|.
+---     - emsg_silent: (boolean) |:silent!|.
+---     - unsilent: (boolean) |:unsilent|.
+---     - sandbox: (boolean) |:sandbox|.
+---     - noautocmd: (boolean) |:noautocmd|.
+---     - browse: (boolean) |:browse|.
+---     - confirm: (boolean) |:confirm|.
+---     - hide: (boolean) |:hide|.
+---     - horizontal: (boolean) |:horizontal|.
+---     - keepalt: (boolean) |:keepalt|.
+---     - keepjumps: (boolean) |:keepjumps|.
+---     - keepmarks: (boolean) |:keepmarks|.
+---     - keeppatterns: (boolean) |:keeppatterns|.
+---     - lockmarks: (boolean) |:lockmarks|.
+---     - noswapfile: (boolean) |:noswapfile|.
+---     - tab: (integer) |:tab|. -1 when omitted.
+---     - verbose: (integer) |:verbose|. -1 when omitted.
+---     - vertical: (boolean) |:vertical|.
+---     - split: (string) Split modifier string, is an empty string when there's no split
+---                       modifier. If there is a split modifier it can be one of:
+---       - "aboveleft": |:aboveleft|.
+---       - "belowright": |:belowright|.
+---       - "topleft": |:topleft|.
+---       - "botright": |:botright|.
 function vim.api.nvim_parse_cmd(str, opts) end
 
 --- Parse a Vimscript expression.
@@ -1884,7 +1988,56 @@ function vim.api.nvim_parse_cmd(str, opts) end
 ---                  highlighted region and represent line, starting column
 ---                  and ending column (latter exclusive: one should highlight
 ---                  region [start_col, end_col)).
---- @return table<string,any>
+--- @return table<string,any> # 
+--- - AST: top-level dict with these keys:
+---   - "error": Dict with error, present only if parser saw some
+---            error. Contains the following keys:
+---     - "message": String, error message in printf format, translated.
+---                  Must contain exactly one "%.*s".
+---     - "arg": String, error message argument.
+---   - "len": Amount of bytes successfully parsed. With flags equal to ""
+---            that should be equal to the length of expr string.
+---            ("Successfully parsed" here means "participated in AST
+---             creation", not "till the first error".)
+---   - "ast": AST, either nil or a dict with these keys:
+---     - "type": node type, one of the value names from ExprASTNodeType
+---               stringified without "kExprNode" prefix.
+---     - "start": a pair `[line, column]` describing where node is "started"
+---                where "line" is always 0 (will not be 0 if you will be
+---                using this API on e.g. ":let", but that is not
+---                present yet). Both elements are Integers.
+---     - "len": “length” of the node. This and "start" are there for
+---              debugging purposes primary (debugging parser and providing
+---              debug information).
+---     - "children": a list of nodes described in top/"ast". There always
+---                   is zero, one or two children, key will not be present
+---                   if node has no children. Maximum number of children
+---                   may be found in node_maxchildren array.
+--- - Local values (present only for certain nodes):
+---   - "scope": a single Integer, specifies scope for "Option" and
+---              "PlainIdentifier" nodes. For "Option" it is one of
+---              ExprOptScope values, for "PlainIdentifier" it is one of
+---              ExprVarScope values.
+---   - "ident": identifier (without scope, if any), present for "Option",
+---              "PlainIdentifier", "PlainKey" and "Environment" nodes.
+---   - "name": Integer, register name (one character) or -1. Only present
+---           for "Register" nodes.
+---   - "cmp_type": String, comparison type, one of the value names from
+---                 ExprComparisonType, stringified without "kExprCmp"
+---                 prefix. Only present for "Comparison" nodes.
+---   - "ccs_strategy": String, case comparison strategy, one of the
+---                     value names from ExprCaseCompareStrategy,
+---                     stringified without "kCCStrategy" prefix. Only
+---                     present for "Comparison" nodes.
+---   - "augmentation": String, augmentation type for "Assignment" nodes.
+---                     Is either an empty string, "Add", "Subtract" or
+---                     "Concat" for "=", "+=", "-=" or ".=" respectively.
+---   - "invert": Boolean, true if result of comparison needs to be
+---               inverted. Only present for "Comparison" nodes.
+---   - "ivalue": Integer, integer value for "Integer" nodes.
+---   - "fvalue": Float, floating-point value for "Float" nodes.
+---   - "svalue": String, value for "SingleQuotedString" and
+---               "DoubleQuotedString" nodes.
 function vim.api.nvim_parse_expression(expr, flags, highlight) end
 
 --- Pastes at cursor (in any mode), and sets "redo" so dot (`.`) will repeat
@@ -1922,7 +2075,9 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end
 ---              • 1: starts the paste (exactly once)
 ---              • 2: continues the paste (zero or more times)
 ---              • 3: ends the paste (exactly once)
---- @return boolean
+--- @return boolean # 
+--- - true: Client may continue pasting.
+--- - false: Client should cancel the paste.
 function vim.api.nvim_paste(data, crlf, phase) end
 
 --- Puts text at cursor, in any mode. For dot-repeatable input, use
@@ -2189,7 +2344,7 @@ function vim.api.nvim_set_vvar(name, value) end
 --- characters including <Tab> count as one cell.
 ---
 --- @param text string Some text
---- @return integer
+--- @return integer # Number of cells
 function vim.api.nvim_strwidth(text) end
 
 --- Removes a tab-scoped (t:) variable
@@ -2201,32 +2356,32 @@ function vim.api.nvim_tabpage_del_var(tabpage, name) end
 --- Gets the tabpage number
 ---
 --- @param tabpage integer Tabpage handle, or 0 for current tabpage
---- @return integer
+--- @return integer # Tabpage number
 function vim.api.nvim_tabpage_get_number(tabpage) end
 
 --- Gets a tab-scoped (t:) variable
 ---
 --- @param tabpage integer Tabpage handle, or 0 for current tabpage
 --- @param name string Variable name
---- @return any
+--- @return any # Variable value
 function vim.api.nvim_tabpage_get_var(tabpage, name) end
 
 --- Gets the current window in a tabpage
 ---
 --- @param tabpage integer Tabpage handle, or 0 for current tabpage
---- @return integer
+--- @return integer # Window handle
 function vim.api.nvim_tabpage_get_win(tabpage) end
 
 --- Checks if a tabpage is valid
 ---
 --- @param tabpage integer Tabpage handle, or 0 for current tabpage
---- @return boolean
+--- @return boolean # true if the tabpage is valid, false otherwise
 function vim.api.nvim_tabpage_is_valid(tabpage) end
 
 --- Gets the windows in a tabpage
 ---
 --- @param tabpage integer Tabpage handle, or 0 for current tabpage
---- @return integer[]
+--- @return integer[] # List of windows in `tabpage`
 function vim.api.nvim_tabpage_list_wins(tabpage) end
 
 --- Sets a tab-scoped (t:) variable
@@ -2249,7 +2404,7 @@ function vim.api.nvim_tabpage_set_win(tabpage, win) end
 --- @param window integer Window handle, or 0 for current window
 --- @param fun function Function to call inside the window (currently Lua callable
 ---            only)
---- @return any
+--- @return any # Return value of function.
 function vim.api.nvim_win_call(window, fun) end
 
 --- Closes the window (like `:close` with a `window-ID`).
@@ -2269,7 +2424,7 @@ function vim.api.nvim_win_del_var(window, name) end
 --- Gets the current buffer in a window
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer
+--- @return integer # Buffer handle
 function vim.api.nvim_win_get_buf(window) end
 
 --- Gets window configuration.
@@ -2279,7 +2434,7 @@ function vim.api.nvim_win_get_buf(window) end
 --- `relative` is empty for normal windows.
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return vim.api.keyset.win_config
+--- @return vim.api.keyset.win_config # Map defining the window configuration, see |nvim_open_win()|
 function vim.api.nvim_win_get_config(window) end
 
 --- Gets the (1,0)-indexed, buffer-relative cursor position for a given window
@@ -2288,19 +2443,19 @@ function vim.api.nvim_win_get_config(window) end
 ---
 --- @see `getcurpos()`
 --- @param window integer Window handle, or 0 for current window
---- @return integer[]
+--- @return integer[] # (row, col) tuple
 function vim.api.nvim_win_get_cursor(window) end
 
 --- Gets the window height
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer
+--- @return integer # Height as a count of rows
 function vim.api.nvim_win_get_height(window) end
 
 --- Gets the window number
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer
+--- @return integer # Window number
 function vim.api.nvim_win_get_number(window) end
 
 --- @deprecated
@@ -2312,26 +2467,26 @@ function vim.api.nvim_win_get_option(window, name) end
 --- Gets the window position in display cells. First position is zero.
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer[]
+--- @return integer[] # (row, col) tuple with the window position
 function vim.api.nvim_win_get_position(window) end
 
 --- Gets the window tabpage
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer
+--- @return integer # Tabpage that contains the window
 function vim.api.nvim_win_get_tabpage(window) end
 
 --- Gets a window-scoped (w:) variable
 ---
 --- @param window integer Window handle, or 0 for current window
 --- @param name string Variable name
---- @return any
+--- @return any # Variable value
 function vim.api.nvim_win_get_var(window, name) end
 
 --- Gets the window width
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return integer
+--- @return integer # Width as a count of columns
 function vim.api.nvim_win_get_width(window) end
 
 --- Closes the window and hide the buffer it contains (like `:hide` with a
@@ -2347,7 +2502,7 @@ function vim.api.nvim_win_hide(window) end
 --- Checks if a window is valid
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return boolean
+--- @return boolean # true if the window is valid, false otherwise
 function vim.api.nvim_win_is_valid(window) end
 
 --- Sets the current buffer in a window, without side effects
@@ -2434,5 +2589,7 @@ function vim.api.nvim_win_set_width(window, width) end
 ---             • end_vcol: Ending virtual column index on "end_row", 0-based
 ---               exclusive, rounded up to full screen lines. When omitted
 ---               include the whole line.
---- @return table<string,any>
+--- @return table<string,any> # Dict containing text height information, with these keys:
+--- - all: The total number of screen lines occupied by the range.
+--- - fill: The number of diff filler or virtual lines among them.
 function vim.api.nvim_win_text_height(window, opts) end
diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index 234028b972..095daaeb21 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -276,7 +276,7 @@ local function get_api_meta()
 
     if not deprecated then
       r.desc = fun.desc
-      r.return_desc = fun.returns[1].desc
+      r.returns_desc = fun.returns[1].desc
     end
 
     ret[fun.name] = r
@@ -370,10 +370,9 @@ local function render_api_meta(_f, fun, write)
   end
 
   if fun.returns ~= '' then
-    local ret_desc = fun.returns_desc and ' : ' .. fun.returns_desc or ''
-    ret_desc = util.md_to_vimdoc(ret_desc, 0, 0, 74)
+    local ret_desc = fun.returns_desc and ' # ' .. fun.returns_desc or ''
     local ret = LUA_API_RETURN_OVERRIDES[fun.name] or fun.returns
-    write('--- @return ' .. ret .. ret_desc)
+    write(util.prefix('--- ', '@return ' .. ret .. ret_desc))
   end
   local param_str = table.concat(param_names, ', ')
 
diff --git a/scripts/util.lua b/scripts/util.lua
index 6343ad4b21..dda18fb807 100644
--- a/scripts/util.lua
+++ b/scripts/util.lua
@@ -173,6 +173,19 @@ local function parse_md(text)
   return extract(root) or {}
 end
 
+--- Prefixes each line in `text`.
+---
+--- Does not wrap, that's not important for "meta" files? (You probably want md_to_vimdoc instead.)
+---
+--- @param text string
+--- @param prefix_ string
+function M.prefix(prefix_, text)
+  if (text):find('\n$') then
+    return text:gsub('([^\n]*)[\t ]*\n', prefix_ .. '%1\n')
+  end
+  return prefix_ .. text:gsub('([^\n]*)[\t ]*\n', '%1\n' .. prefix_)
+end
+
 --- @param x string
 --- @param start_indent integer
 --- @param indent integer