feat: improve return type annotations for vim.api.*

runtime/lua/vim/_meta/api.lua

@@ -320,7 +320,7 @@ 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 integer[]
+--- @return vim.api.keyset.get_extmark_item
 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
@@ -376,14 +376,14 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 ---                 if their start position is less than `start`
 ---               • type: Filter marks by type: "highlight", "sign",
 ---                 "virt_text" and "virt_lines"
---- @return any[]
+--- @return vim.api.keyset.get_extmark_item[]
 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 table<string,any>[]
+--- @return vim.api.keyset.keymap[]
 function vim.api.nvim_buf_get_keymap(buffer, mode) end
 
 --- Gets a line-range from the buffer.
@@ -1153,7 +1153,7 @@ 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 any[]
+--- @return vim.api.keyset.get_autocmds.ret[]
 function vim.api.nvim_get_autocmds(opts) end
 
 --- Gets information about a channel.
@@ -1179,7 +1179,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,any>
+--- @return table<string,integer>
 function vim.api.nvim_get_color_map() end
 
 --- Gets a map of global (non-buffer-local) Ex commands.
@@ -1229,7 +1229,7 @@ function vim.api.nvim_get_current_win() end
 ---                instead of effective definition `:hi-link`.
 ---              • create: (boolean, default true) When highlight group
 ---                doesn't exist create it.
---- @return table<string,any>
+--- @return vim.api.keyset.hl_info
 function vim.api.nvim_get_hl(ns_id, opts) end
 
 --- @deprecated
@@ -1264,7 +1264,7 @@ 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 table<string,any>[]
+--- @return vim.api.keyset.keymap[]
 function vim.api.nvim_get_keymap(mode) end
 
 --- Returns a `(row, col, buffer, buffername)` tuple representing the position
@@ -1274,18 +1274,18 @@ function vim.api.nvim_get_keymap(mode) end
 ---
 --- @param name string Mark name
 --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
---- @return any[]
+--- @return vim.api.keyset.get_mark
 function vim.api.nvim_get_mark(name, opts) end
 
 --- Gets the current mode. `mode()` "blocking" is true if Nvim is waiting for
 --- input.
 ---
---- @return table<string,any>
+--- @return vim.api.keyset.get_mode
 function vim.api.nvim_get_mode() end
 
 --- Gets existing, non-anonymous `namespace`s.
 ---
---- @return table<string,any>
+--- @return table<string,integer>
 function vim.api.nvim_get_namespaces() end
 
 --- @deprecated
@@ -1295,7 +1295,7 @@ function vim.api.nvim_get_option(name) end
 
 --- @deprecated
 --- @param name string
---- @return table<string,any>
+--- @return vim.api.keyset.get_option_info
 function vim.api.nvim_get_option_info(name) end
 
 --- Gets the option information for one option from arbitrary buffer or window
@@ -1325,7 +1325,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 table<string,any>
+--- @return vim.api.keyset.get_option_info
 function vim.api.nvim_get_option_info2(name, opts) end
 
 --- Gets the value of an option. The behavior of this function matches that of
@@ -1637,7 +1637,7 @@ 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 table<string,any>
+--- @return vim.api.keyset.parse_cmd
 function vim.api.nvim_parse_cmd(str, opts) end
 
 --- Parse a Vimscript expression.
@@ -1985,7 +1985,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 table<string,any>
+--- @return vim.api.keyset.float_config
 function vim.api.nvim_win_get_config(window) end
 
 --- Gets the (1,0)-indexed, buffer-relative cursor position for a given window

runtime/lua/vim/_meta/api_keysets_extra.lua

@@ -0,0 +1,167 @@
+--- @meta _
+error('Cannot require a meta file')
+
+--- Extra types we can't generate keysets for
+
+--- @class vim.api.keyset.extmark_details
+--- @field ns_id integer
+--- @field right_gravity boolean
+---
+--- @field end_row? integer
+--- @field end_col? integer
+--- @field end_right_gravity? integer
+---
+--- @field priority? integer
+---
+--- @field undo_restore? false
+--- @field invalidate? true
+--- @field invalid? true
+---
+--- @field hl_group? string
+--- @field hl_eol? boolean
+---
+--- @field conceal? boolean
+--- @field spell? boolean
+--- @field ui_watched? boolean
+--- @field url? boolean
+--- @field hl_mode? string
+---
+--- @field virt_text? {[1]: string, [2]: string}[]
+--- @field virt_text_hide? boolean
+--- @field virt_text_repeat_linebreak? boolean
+--- @field virt_text_win_col? integer
+--- @field virt_text_pos? string
+---
+--- @field virt_lines? {[1]: string, [2]: string}[][]
+--- @field virt_lines_above? boolean
+--- @field virt_lines_leftcol? boolean
+---
+--- @field sign_text? string
+--- @field sign_name? string
+--- @field sign_hl_group? string
+--- @field number_hl_group? string
+--- @field line_hl_group? string
+--- @field cursorline_hl_group? string
+
+--- @class vim.api.keyset.get_extmark_item
+--- @field [1] integer row
+--- @field [2] integer col
+--- @field [3] vim.api.keyset.extmark_details?
+
+--- @class vim.api.keyset.get_mark
+--- @field [1] integer row
+--- @field [2] integer col
+--- @field [3] integer buffer
+--- @field [4] string buffername
+
+--- @class vim.api.keyset.get_autocmds.ret
+--- @field id? integer
+--- @field group? integer
+--- @field group_name? integer
+--- @field desc? string
+--- @field event? string
+--- @field command? string
+--- @field callback? function
+--- @field once? boolean
+--- @field pattern? string
+--- @field buflocal? boolean
+--- @field buffer? integer
+
+--- @class vim.api.keyset.command_info
+--- @field name string
+--- @field definition string
+--- @field script_id integer
+--- @field bang boolean
+--- @field bar boolean
+--- @field register boolean
+--- @field keepscript boolean
+--- @field preview boolean
+--- @field nargs string
+--- @field complete? string
+--- @field complete_arg? string
+--- @field count? string
+--- @field range? string
+--- @field addr? string
+
+--- @class vim.api.keyset.hl_info.base
+--- @field reverse? true
+--- @field bold? true
+--- @field italic? true
+--- @field underline? true
+--- @field undercurl? true
+--- @field underdouble? true
+--- @field underdotted? true
+--- @field underdashed? true
+--- @field standout? true
+--- @field strikethrough? true
+--- @field altfont? true
+--- @field nocombine? true
+
+--- @class vim.api.keyset.hl_info.cterm : vim.api.keyset.hl_info.base
+--- @field ctermfg? integer
+--- @field ctermbg? integer
+--- @field foreground? integer
+--- @field background? integer
+
+--- @class vim.api.keyset.hl_info : vim.api.keyset.hl_info.base
+--- @field fg? integer
+--- @field bg? integer
+--- @field sp? integer
+--- @field default? true
+--- @field link? string
+--- @field blend? integer
+--- @field cterm? vim.api.keyset.hl_info.cterm
+
+--- @class vim.api.keyset.get_mode
+--- @field blocking boolean
+--- @field mode string
+
+--- @class vim.api.keyset.get_option_info
+--- @field name string
+--- @field shortname string
+--- @field scope 'buf'|'win'|'global'
+--- @field global_local boolean
+--- @field commalist boolean
+--- @field flaglist boolean
+--- @field was_set boolean
+--- @field last_set_id integer
+--- @field last_set_linenr integer
+--- @field last_set_chan integer
+--- @field type 'string'|'boolean'|'number'
+--- @field default string|boolean|integer
+--- @field allow_duplicates boolean
+
+--- @class vim.api.keyset.parse_cmd.mods
+--- @field filter { force: boolean, pattern: string }
+--- @field silent boolean
+--- @field emsg_silent boolean
+--- @field unsilent boolean
+--- @field sandbox boolean
+--- @field noautocmd boolean
+--- @field tab integer
+--- @field verbose integer
+--- @field browse boolean
+--- @field confirm boolean
+--- @field hide boolean
+--- @field keepalt boolean
+--- @field keepjumps boolean
+--- @field keepmarks boolean
+--- @field keeppatterns boolean
+--- @field lockmarks boolean
+--- @field noswapfile boolean
+--- @field vertical boolean
+--- @field horizontal boolean
+--- @field split ''|'botright'|'topleft'|'belowright'|'aboveleft'
+
+--- @class vim.api.keyset.parse_cmd
+--- @field addr 'line'|'arg'|'buf'|'load'|'win'|'tab'|'qf'|'none'|'?'
+--- @field args string[]
+--- @field bang boolean
+--- @field cmd string
+--- @field magic {bar: boolean, file: boolean}
+--- @field mods vim.api.keyset.parse_cmd.mods
+--- @field nargs '0'|'1'|'?'|'+'|'*'
+--- @field nextcmd string
+--- @field range? integer[]
+--- @field count? integer
+--- @field reg? string

scripts/gen_eval_files.lua

@@ -1,3 +1,5 @@
+#!/usr/bin/env -S nvim -l
+
 -- Generator for various vimdoc and Lua type files
 
 local DEP_API_METADATA = 'build/api_metadata.mpack'
@@ -17,6 +19,31 @@ local DEP_API_DOC = 'runtime/doc/api.mpack'
 --- @field remote boolean
 --- @field since integer
 
+local LUA_API_RETURN_OVERRIDES = {
+  nvim_buf_get_command = 'table<string,vim.api.keyset.command_info>',
+  nvim_buf_get_extmark_by_id = 'vim.api.keyset.get_extmark_item',
+  nvim_buf_get_extmarks = 'vim.api.keyset.get_extmark_item[]',
+  nvim_buf_get_keymap = 'vim.api.keyset.keymap[]',
+  nvim_get_autocmds = 'vim.api.keyset.get_autocmds.ret[]',
+  nvim_get_color_map = 'table<string,integer>',
+  nvim_get_command = 'table<string,vim.api.keyset.command_info>',
+  nvim_get_keymap = 'vim.api.keyset.keymap[]',
+  nvim_get_mark = 'vim.api.keyset.get_mark',
+
+  -- Can also return table<string,vim.api.keyset.hl_info>, however we need to
+  -- pick one to get some benefit.
+  -- REVISIT lewrus01 (26/01/24): we can maybe add
+  -- @overload fun(ns: integer, {}): table<string,vim.api.keyset.hl_info>
+  nvim_get_hl = 'vim.api.keyset.hl_info',
+
+  nvim_get_mode = 'vim.api.keyset.get_mode',
+  nvim_get_namespaces = 'table<string,integer>',
+  nvim_get_option_info = 'vim.api.keyset.get_option_info',
+  nvim_get_option_info2 = 'vim.api.keyset.get_option_info',
+  nvim_parse_cmd = 'vim.api.keyset.parse_cmd',
+  nvim_win_get_config = 'vim.api.keyset.float_config',
+}
+
 local LUA_META_HEADER = {
   '--- @meta _',
   '-- THIS FILE IS GENERATED',
@@ -289,11 +316,9 @@ local function render_api_meta(_f, fun, write)
     end
   end
   if fun.returns ~= '' then
-    if fun.returns_desc then
-      write('--- @return ' .. fun.returns .. ' : ' .. fun.returns_desc)
-    else
-      write('--- @return ' .. fun.returns)
-    end
+    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)
   end
   local param_str = table.concat(param_names, ', ')