docs(api): document types using LuaCATS types

- Render Lua types in api.txt.

- Added `DictAs(name)` API type which acts the same as `Dict` (no parens)
  when generating the dispatchers, but acts the same as `Dict(name)`
  when generating docs.

- Added `Tuple(...)` API type which is the treated the as `Array` for
  generating the dispatchers, but is used to document richer types.

- Added `Enum(...)` API type to better document enums

- Improve typing of some API functions.

- Improve c_grammar to properly parse API types and replace string pattern
  logic in the parsers.

- Removed all the hardcoded type overrides in gen_eval_files.lua

runtime/lua/vim/_meta/api.lua

@@ -27,7 +27,7 @@ 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> # Dict containing these keys:
+--- @return table<string,number> # 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
@@ -37,7 +37,7 @@ function vim.api.nvim__get_lib_dir() end
 
 --- Find files in runtime directories
 ---
---- @param pat any[] pattern of files to search for
+--- @param pat string[] 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[] # list of absolute paths to the found files
@@ -348,7 +348,7 @@ function vim.api.nvim_buf_get_changedtick(buffer) end
 ---
 --- @param buffer integer Buffer id, or 0 for current buffer
 --- @param opts vim.api.keyset.get_commands Optional parameters. Currently not used.
---- @return table<string,any> # Map of maps describing commands.
+--- @return vim.api.keyset.command_info # Map of maps describing commands.
 function vim.api.nvim_buf_get_commands(buffer, opts) end
 
 --- Gets the position (0-indexed) of an `extmark`.
@@ -359,7 +359,7 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end
 --- @param opts vim.api.keyset.get_extmark Optional parameters. Keys:
 --- - 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 # 0-indexed (row, col) tuple or empty list () if extmark id was
+--- @return [integer, integer, vim.api.keyset.extmark_details?] # 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
 
@@ -1096,7 +1096,7 @@ function vim.api.nvim_del_var(name) end
 --- vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
 --- ```
 ---
---- @param chunks any[] List of `[text, hl_group]` pairs, where each is a `text` string highlighted by
+--- @param chunks [string, integer|string][] List of `[text, hl_group]` pairs, where each is a `text` string highlighted by
 --- the (optional) name or ID `hl_group`.
 --- @param history boolean if true, add to `message-history`.
 --- @param opts vim.api.keyset.echo_opts Optional parameters.
@@ -1327,7 +1327,7 @@ function vim.api.nvim_get_color_map() end
 --- @see vim.api.nvim_get_all_options_info
 --- @param opts vim.api.keyset.get_commands Optional parameters. Currently only supports
 --- {"builtin":false}
---- @return table<string,any> # Map of maps describing commands.
+--- @return table<string,vim.api.keyset.command_info> # Map of maps describing commands.
 function vim.api.nvim_get_commands(opts) end
 
 --- Gets a map of the current editor state.
@@ -1427,7 +1427,7 @@ function vim.api.nvim_get_keymap(mode) end
 --- @see vim.api.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 # 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is
+--- @return [integer, integer, integer, string] # 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is
 --- not set.
 function vim.api.nvim_get_mark(name, opts) end
 
@@ -1599,7 +1599,7 @@ function vim.api.nvim_list_bufs() end
 
 --- Get information about all open channels.
 ---
---- @return any[] # Array of Dictionaries, each describing a channel with
+--- @return table<string,any>[] # Array of Dictionaries, each describing a channel with
 --- the format specified at |nvim_get_chan_info()|.
 function vim.api.nvim_list_chans() end
 
@@ -1623,7 +1623,7 @@ function vim.api.nvim_list_tabpages() end
 --- vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)
 --- ```
 ---
---- @return any[] # Array of UI dictionaries, each with these keys:
+--- @return table<string,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|)
@@ -1865,7 +1865,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 vim.api.keyset.parse_cmd # Dict containing command information, with these keys:
+--- @return vim.api.keyset.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.

runtime/lua/vim/_meta/api_keysets.lua

@@ -24,15 +24,15 @@ error('Cannot require a meta file')
 
 --- @class vim.api.keyset.cmd
 --- @field cmd? string
---- @field range? any[]
+--- @field range? integer[]
 --- @field count? integer
 --- @field reg? string
 --- @field bang? boolean
 --- @field args? string[]
---- @field magic? table<string,any>
---- @field mods? table<string,any>
---- @field nargs? integer|string
---- @field addr? string
+--- @field magic? vim.api.keyset.cmd.magic
+--- @field mods? vim.api.keyset.cmd.mods
+--- @field nargs? integer|"?"|"+"|"*"
+--- @field addr? "line"|"arg"|"buf"|"load"|"win"|"tab"|"qf"|"none"|"?"
 --- @field nextcmd? string
 
 --- @class vim.api.keyset.cmd_magic
@@ -79,7 +79,7 @@ error('Cannot require a meta file')
 
 --- @class vim.api.keyset.create_autocmd
 --- @field buffer? integer
---- @field callback? string|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean?)
+--- @field callback? string|fun(args: vim.api.keyset.create_autocmd.callback_args): boolean?
 --- @field command? string
 --- @field desc? string
 --- @field group? integer|string
@@ -294,9 +294,9 @@ error('Cannot require a meta file')
 --- @field col? number
 --- @field width? integer
 --- @field height? integer
---- @field anchor? 'NW'|'NE'|'SW'|'SE'
---- @field relative? 'cursor'|'editor'|'laststatus'|'mouse'|'tabline'|'win'
---- @field split? 'left'|'right'|'above'|'below'
+--- @field anchor? "NW"|"NE"|"SW"|"SE"
+--- @field relative? "cursor"|"editor"|"laststatus"|"mouse"|"tabline"|"win"
+--- @field split? "left"|"right"|"above"|"below"
 --- @field win? integer
 --- @field bufpos? integer[]
 --- @field external? boolean
@@ -304,12 +304,12 @@ error('Cannot require a meta file')
 --- @field mouse? boolean
 --- @field vertical? boolean
 --- @field zindex? integer
---- @field border? 'none'|'single'|'double'|'rounded'|'solid'|'shadow'|string[]
+--- @field border? string[]|"none"|"single"|"double"|"rounded"|"solid"|"shadow"
 --- @field title? any
---- @field title_pos? 'center'|'left'|'right'
+--- @field title_pos? "center"|"left"|"right"
 --- @field footer? any
---- @field footer_pos? 'center'|'left'|'right'
---- @field style? 'minimal'
+--- @field footer_pos? "center"|"left"|"right"
+--- @field style? "minimal"
 --- @field noautocmd? boolean
 --- @field fixed? boolean
 --- @field hide? boolean

runtime/lua/vim/_meta/api_keysets_extra.lua

@@ -54,12 +54,6 @@ error('Cannot require a meta file')
 --- @field [3] integer col
 --- @field [4] 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
@@ -212,7 +206,7 @@ error('Cannot require a meta file')
 --- @field default string|boolean|integer
 --- @field allows_duplicates boolean
 
---- @class vim.api.keyset.parse_cmd.mods
+--- @class vim.api.keyset.cmd.mods
 --- @field filter { force: boolean, pattern: string }
 --- @field silent boolean
 --- @field emsg_silent boolean
@@ -234,18 +228,9 @@ error('Cannot require a meta file')
 --- @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
+--- @class vim.api.keyset.cmd.magic
+--- @field bar boolean
+--- @field file boolean
 
 --- @class vim.api.keyset.eval_statusline_ret.highlight
 --- @field start integer