From fe794153ed3f267bfba13b78fde67b999fe7e600 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Mon, 13 Jul 2026 20:01:55 +0200
Subject: [PATCH] feat(docs): mark optional API parameters

---
 runtime/doc/api.txt               | 86 +++++++++++++++----------------
 runtime/lua/vim/_meta/api.gen.lua | 80 ++++++++++++++--------------
 src/gen/c_grammar.lua             | 13 +++++
 src/gen/cdoc_parser.lua           | 11 ++++
 src/gen/gen_api_dispatch.lua      |  7 +--
 5 files changed, 108 insertions(+), 89 deletions(-)

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 658501cf14..17f7e6112a 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -685,7 +685,7 @@ nvim_echo({chunks}, {history}, {opts})                           *nvim_echo()*
                    pairs, where each is a `text` string highlighted by the
                    (optional) name or ID `hl_group`.
       • {history}  (`boolean`) if true, add to |message-history|.
-      • {opts}     (`vim.api.keyset.echo_opts`) Optional parameters.
+      • {opts}     (`vim.api.keyset.echo_opts?`) Optional parameters.
                    • data (`table?`) Dict of arbitrary data, available in
                      |Progress| |event-data|.
                    • err (`boolean?`) Treat the message like `:echoerr`. Sets
@@ -725,7 +725,7 @@ nvim_eval_statusline({str}, {opts})                   *nvim_eval_statusline()*
 
     Parameters: ~
       • {str}   (`string`) Statusline string (see 'statusline').
-      • {opts}  (`vim.api.keyset.eval_statusline`) Optional parameters.
+      • {opts}  (`vim.api.keyset.eval_statusline?`) Optional parameters.
                 • fillchar: (string) Character to fill blank spaces in the
                   statusline (see 'fillchars'). Treated as single-width even
                   if it isn't.
@@ -894,7 +894,7 @@ nvim_get_context({opts})                                  *nvim_get_context()*
         Since: 0.4.0
 
     Parameters: ~
-      • {opts}  (`vim.api.keyset.context`) Optional parameters.
+      • {opts}  (`vim.api.keyset.context?`) Optional parameters.
                 • types: List of |context-types| ("regs", "jumps", "bufs",
                   "gvars", …) to gather, or empty for "all".
 
@@ -951,7 +951,7 @@ nvim_get_hl({ns_id}, {opts})                                   *nvim_get_hl()*
       • {ns_id}  (`integer`) Get highlight groups for namespace ns_id
                  |nvim_get_namespaces()|. Use 0 to get global highlight groups
                  |:highlight|.
-      • {opts}   (`vim.api.keyset.get_highlight`) Options dict:
+      • {opts}   (`vim.api.keyset.get_highlight?`) Options dict:
                  • create: (boolean, default true) When highlight group
                    doesn't exist create it.
                  • id: (integer) Get a highlight definition by id.
@@ -985,7 +985,7 @@ nvim_get_hl_ns({opts})                                      *nvim_get_hl_ns()*
         Since: 0.10.0
 
     Parameters: ~
-      • {opts}  (`vim.api.keyset.get_ns`) Optional parameters
+      • {opts}  (`vim.api.keyset.get_ns?`) Optional parameters
                 • winid: (number) |window-ID| for retrieving a window's
                   highlight namespace. A value of -1 is returned when
                   |nvim_win_set_hl_ns()| has not been called for the window
@@ -1022,7 +1022,7 @@ nvim_get_mark({name}, {opts})                                *nvim_get_mark()*
 
     Parameters: ~
       • {name}  (`string`) Mark name
-      • {opts}  (`vim.api.keyset.empty`) Optional parameters. Reserved for
+      • {opts}  (`vim.api.keyset.empty?`) Optional parameters. Reserved for
                 future use.
 
     Return: ~
@@ -1294,7 +1294,7 @@ nvim_open_term({buf}, {opts})                               *nvim_open_term()*
     Parameters: ~
       • {buf}   (`integer`) Buffer which displays the PTY output. The initial
                 buffer contents (if any) will be written to the PTY.
-      • {opts}  (`vim.api.keyset.open_term`) Optional parameters.
+      • {opts}  (`vim.api.keyset.open_term?`) Optional parameters.
                 • force_crlf: (boolean, default true) Convert "\n" to "\r\n".
                 • on_input: Lua callback for input sent, i e keypresses in
                   terminal mode. Note: keypresses are sent raw as they would
@@ -1419,7 +1419,7 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
                   |cmdline-completion|.
       • {finish}  (`boolean`) Finish the completion and dismiss the popup
                   menu. Implies {insert}.
-      • {opts}    (`vim.api.keyset.empty`) Optional parameters. Reserved for
+      • {opts}    (`vim.api.keyset.empty?`) Optional parameters. Reserved for
                   future use.
 
                                                       *nvim_set_client_info()*
@@ -1654,9 +1654,9 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {opts})              *nvim_set_keymap()*
                 mode, or both, respectively
       • {lhs}   (`string`) Left-hand-side |{lhs}| of the mapping.
       • {rhs}   (`string`) Right-hand-side |{rhs}| of the mapping.
-      • {opts}  (`vim.api.keyset.keymap`) Optional parameters map: Accepts all
-                |:map-arguments| as keys except <buffer>, values are booleans
-                (default false). Also:
+      • {opts}  (`vim.api.keyset.keymap?`) Optional parameters map: Accepts
+                all |:map-arguments| as keys except <buffer>, values are
+                booleans (default false). Also:
                 • "callback" Lua function called in place of {rhs}.
                 • "desc" human-readable description.
                 • "noremap" disables |recursive_mapping|, like |:noremap|
@@ -1734,7 +1734,7 @@ nvim__complete_set({index}, {opts})                     *nvim__complete_set()*
 
     Parameters: ~
       • {index}  (`integer`) Completion candidate index
-      • {opts}   (`vim.api.keyset.complete_set`) Optional parameters.
+      • {opts}   (`vim.api.keyset.complete_set?`) Optional parameters.
                  • info: (string) info text.
 
     Return: ~
@@ -1777,7 +1777,7 @@ nvim__get_runtime({pat}, {all}, {opts})                  *nvim__get_runtime()*
     Parameters: ~
       • {pat}   (`string[]`) pattern of files to search for
       • {all}   (`boolean`) whether to return all matches or only the first
-      • {opts}  (`vim.api.keyset.runtime`) is_lua: only search Lua subdirs
+      • {opts}  (`vim.api.keyset.runtime?`) is_lua: only search Lua subdirs
 
     Return: ~
         (`string[]`) list of absolute paths to the found files
@@ -1867,7 +1867,7 @@ nvim__redraw({opts})                                          *nvim__redraw()*
         Since: 0.10.0
 
     Parameters: ~
-      • {opts}  (`vim.api.keyset.redraw`) Optional parameters.
+      • {opts}  (`vim.api.keyset.redraw?`) Optional parameters.
                 • buf: Target a specific buffer number as described below.
                 • cursor: Immediately update cursor position on the screen in
                   `win` or the current window.
@@ -1987,7 +1987,7 @@ nvim_exec2({src}, {opts})                                       *nvim_exec2()*
 
     Parameters: ~
       • {src}   (`string`) Vimscript code
-      • {opts}  (`vim.api.keyset.exec_opts`) Optional parameters.
+      • {opts}  (`vim.api.keyset.exec_opts?`) Optional parameters.
                 • output: (boolean, default false) Whether to capture and
                   return all (non-error, non-shell |:!|) output.
 
@@ -2093,7 +2093,7 @@ nvim_clear_autocmds({opts})                            *nvim_clear_autocmds()*
         Since: 0.7.0
 
     Parameters: ~
-      • {opts}  (`vim.api.keyset.clear_autocmds`) Optional parameters:
+      • {opts}  (`vim.api.keyset.clear_autocmds?`) Optional parameters:
                 • buf: (`integer?`) Select |autocmd-buflocal| autocommands.
                   Not allowed with {pattern}.
                 • event: (`vim.api.keyset.events|vim.api.keyset.events[]?`)
@@ -2123,7 +2123,7 @@ nvim_create_augroup({name}, {opts})                    *nvim_create_augroup()*
 
     Parameters: ~
       • {name}  (`string`) Group name
-      • {opts}  (`vim.api.keyset.create_augroup`) Optional parameters:
+      • {opts}  (`vim.api.keyset.create_augroup?`) Optional parameters:
                 • clear (`boolean?`, default: true) Clear existing commands in
                   the group |autocmd-groups|.
 
@@ -2165,7 +2165,7 @@ nvim_create_autocmd({event}, {opts})                   *nvim_create_autocmd()*
     Parameters: ~
       • {event}  (`vim.api.keyset.events|vim.api.keyset.events[]`) Event(s)
                  that will trigger the handler (`callback` or `command`).
-      • {opts}   (`vim.api.keyset.create_autocmd`) Options dict:
+      • {opts}   (`vim.api.keyset.create_autocmd?`) Options dict:
                  • buf (`integer?`) Buffer id for buffer-local autocommands
                    |autocmd-buflocal|. Not allowed with {pattern}.
                  • callback (`function|string?`) Lua function (or Vimscript
@@ -2256,7 +2256,7 @@ nvim_exec_autocmds({event}, {opts})                     *nvim_exec_autocmds()*
     Parameters: ~
       • {event}  (`vim.api.keyset.events|vim.api.keyset.events[]`) Event(s) to
                  execute.
-      • {opts}   (`vim.api.keyset.exec_autocmds`) Optional filters:
+      • {opts}   (`vim.api.keyset.exec_autocmds?`) Optional filters:
                  • buf (`integer?`) Buffer where the event is applied.
                    |autocmd-buflocal| Not allowed with {pattern}.
                  • data (`any`): Arbitrary data passed to the callback. See
@@ -2296,7 +2296,7 @@ nvim_get_autocmds({opts})                                *nvim_get_autocmds()*
         Since: 0.7.0
 
     Parameters: ~
-      • {opts}  (`vim.api.keyset.get_autocmds`) Dict with at least one of
+      • {opts}  (`vim.api.keyset.get_autocmds?`) Dict with at least one of
                 these keys:
                 • buf: (`integer[]|integer?`) Buffer id or list of buffer ids,
                   for buffer-local autocommands |autocmd-buflocal|. Not
@@ -2367,7 +2367,7 @@ nvim_buf_attach({buf}, {send_buffer}, {opts})              *nvim_buf_attach()*
                        `nvim_buf_lines_event`. Else the first notification
                        will be `nvim_buf_changedtick_event`. Not for Lua
                        callbacks.
-      • {opts}         (`vim.api.keyset.buf_attach`) Optional parameters.
+      • {opts}         (`vim.api.keyset.buf_attach?`) Optional parameters.
                        • on_bytes: Called on granular changes (compared to
                          on_lines). Not called on buffer reload (`:checktime`,
                          `:edit`, …), see `on_reload:`. Return a
@@ -2512,7 +2512,7 @@ nvim_buf_delete({buf}, {opts})                             *nvim_buf_delete()*
 
     Parameters: ~
       • {buf}   (`integer`) Buffer id, or 0 for current buffer
-      • {opts}  (`vim.api.keyset.buf_delete`) Optional parameters. Keys:
+      • {opts}  (`vim.api.keyset.buf_delete?`) Optional parameters. Keys:
                 • force: Force deletion, ignore unsaved changes.
                 • unload: Unloaded only (|:bunload|), do not delete.
 
@@ -2667,7 +2667,7 @@ nvim_buf_get_text({buf}, {start_row}, {start_col}, {end_row}, {end_col},
       • {end_row}    (`integer`) Last line index, inclusive
       • {end_col}    (`integer`) Ending column (byte offset) on last line,
                      exclusive
-      • {opts}       (`vim.api.keyset.empty`) Optional parameters. Currently
+      • {opts}       (`vim.api.keyset.empty?`) Optional parameters. Currently
                      unused.
 
     Return: ~
@@ -2739,7 +2739,7 @@ nvim_buf_set_keymap({buf}, {mode}, {lhs}, {rhs}, {opts})
       • {mode}  (`string`)
       • {lhs}   (`string`)
       • {rhs}   (`string`)
-      • {opts}  (`vim.api.keyset.keymap`)
+      • {opts}  (`vim.api.keyset.keymap?`)
 
     See also: ~
       • |nvim_set_keymap()|
@@ -2791,7 +2791,7 @@ nvim_buf_set_mark({buf}, {name}, {line}, {col}, {opts})
       • {name}  (`string`) Mark name
       • {line}  (`integer`) Line number
       • {col}   (`integer`) Column/row number
-      • {opts}  (`vim.api.keyset.empty`) Optional parameters. Reserved for
+      • {opts}  (`vim.api.keyset.empty?`) Optional parameters. Reserved for
                 future use.
 
     Return: ~
@@ -2872,7 +2872,7 @@ nvim_buf_create_user_command({buf}, {name}, {cmd}, {opts})
       • {buf}   (`integer`) Buffer id, or 0 for current buffer.
       • {name}  (`string`)
       • {cmd}   (`any`)
-      • {opts}  (`vim.api.keyset.user_command`)
+      • {opts}  (`vim.api.keyset.user_command?`)
 
     See also: ~
       • nvim_create_user_command
@@ -2898,8 +2898,8 @@ nvim_buf_get_commands({buf}, {opts})                 *nvim_buf_get_commands()*
 
     Parameters: ~
       • {buf}   (`integer`) Buffer id, or 0 for current buffer
-      • {opts}  (`vim.api.keyset.get_commands`) Optional parameters. Currently
-                not used.
+      • {opts}  (`vim.api.keyset.get_commands?`) Optional parameters.
+                Currently not used.
 
     Return: ~
         (`vim.api.keyset.command_info`) Map of maps describing commands.
@@ -2931,7 +2931,7 @@ nvim_cmd({cmd}, {opts})                                           *nvim_cmd()*
                 same structure as the return value of |nvim_parse_cmd()|
                 (except "addr", "nargs" and "nextcmd" are ignored). All keys
                 except "cmd" are optional.
-      • {opts}  (`vim.api.keyset.cmd_opts`) Optional parameters.
+      • {opts}  (`vim.api.keyset.cmd_opts?`) Optional parameters.
                 • output: (boolean, default false) Whether to return command
                   output.
 
@@ -2982,7 +2982,7 @@ nvim_create_user_command({name}, {cmd}, {opts})
                 • reg: (string) Register name, if any. <reg>
                 • smods: (table) Command modifiers (structured), same as
                   "mods" in |nvim_parse_cmd()|.
-      • {opts}  (`vim.api.keyset.user_command`) Optional flags:
+      • {opts}  (`vim.api.keyset.user_command?`) Optional flags:
                 • `addr` |:command-addr|
                 • `complete` |:command-complete| command or function
                   |:command-completion-customlist|.
@@ -3017,8 +3017,8 @@ nvim_get_commands({opts})                                *nvim_get_commands()*
         Since: 0.3.0
 
     Parameters: ~
-      • {opts}  (`vim.api.keyset.get_commands`) Optional parameters. Currently
-                only supports {"builtin":false}
+      • {opts}  (`vim.api.keyset.get_commands?`) Optional parameters.
+                Currently only supports {"builtin":false}
 
     Return: ~
         (`table<string,vim.api.keyset.command_info>`) Map of maps describing
@@ -3038,7 +3038,7 @@ nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
 
     Parameters: ~
       • {str}   (`string`) Command line string to parse. Cannot contain "\n".
-      • {opts}  (`vim.api.keyset.empty`) Optional parameters. Reserved for
+      • {opts}  (`vim.api.keyset.empty?`) Optional parameters. Reserved for
                 future use.
 
     Return: ~
@@ -3146,7 +3146,7 @@ nvim_buf_get_extmark_by_id({buf}, {ns_id}, {id}, {opts})
       • {buf}    (`integer`) Buffer id, or 0 for current buffer
       • {ns_id}  (`integer`) Namespace id from |nvim_create_namespace()|
       • {id}     (`integer`) Extmark id
-      • {opts}   (`vim.api.keyset.get_extmark`) Optional parameters. Keys:
+      • {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
@@ -3215,7 +3215,7 @@ nvim_buf_get_extmarks({buf}, {ns_id}, {start}, {end}, {opts})
       • {end}    (`any`) End of range (inclusive): a 0-indexed (row, col) or
                  valid extmark id (whose position defines the bound).
                  |api-indexing|
-      • {opts}   (`vim.api.keyset.get_extmarks`) Optional parameters. Keys:
+      • {opts}   (`vim.api.keyset.get_extmarks?`) Optional parameters. Keys:
                  • details: Whether to include the details dict
                  • hl_name: Whether to include highlight group name instead of
                    id, true if omitted
@@ -3258,7 +3258,7 @@ nvim_buf_set_extmark({buf}, {ns_id}, {line}, {col}, {opts})
                  |api-indexing|
       • {col}    (`integer`) Column where to place the mark, 0-based.
                  |api-indexing|
-      • {opts}   (`vim.api.keyset.set_extmark`) Optional parameters:
+      • {opts}   (`vim.api.keyset.set_extmark?`) Optional parameters:
                  • conceal: (boolean|string)
                    • string: Single char or empty string, enables conceal
                      similar to |:syn-conceal|. Non-empty char is used as
@@ -3450,7 +3450,7 @@ nvim_set_decoration_provider({ns_id}, {opts})
 
     Parameters: ~
       • {ns_id}  (`integer`) Namespace id from |nvim_create_namespace()|
-      • {opts}   (`vim.api.keyset.set_decoration_provider`) Table of
+      • {opts}   (`vim.api.keyset.set_decoration_provider?`) Table of
                  callbacks:
                  • on_buf: called for each buffer being redrawn (once per
                    edit, before window callbacks) >
@@ -3502,7 +3502,7 @@ nvim__ns_set({ns_id}, {opts})                                 *nvim__ns_set()*
 
     Parameters: ~
       • {ns_id}  (`integer`) Namespace
-      • {opts}   (`vim.api.keyset.ns_opts`) Optional parameters to set:
+      • {opts}   (`vim.api.keyset.ns_opts?`) Optional parameters to set:
                  • wins: a list of windows to be scoped in
 
 
@@ -3551,7 +3551,7 @@ nvim_get_option_info2({name}, {opts})                *nvim_get_option_info2()*
 
     Parameters: ~
       • {name}  (`string`) Option name
-      • {opts}  (`vim.api.keyset.option`) Optional parameters
+      • {opts}  (`vim.api.keyset.option?`) Optional parameters
                 • buf: Buffer number. Used for getting buffer local options.
                   Implies {scope} is "local".
                 • scope: One of "global" or "local". Analogous to |:setglobal|
@@ -3572,7 +3572,7 @@ nvim_get_option_value({name}, {opts})                *nvim_get_option_value()*
 
     Parameters: ~
       • {name}  (`string`) Option name
-      • {opts}  (`vim.api.keyset.option`) Optional parameters
+      • {opts}  (`vim.api.keyset.option?`) Optional parameters
                 • buf: Buffer number. Used for getting buffer local options.
                   Implies {scope} is "local".
                 • filetype: |filetype|. Used to get the default option for a
@@ -3602,7 +3602,7 @@ nvim_set_option_value({name}, {value}, {opts})
     Parameters: ~
       • {name}   (`string`) Option name
       • {value}  (`any`) New option value
-      • {opts}   (`vim.api.keyset.option`) Optional parameters
+      • {opts}   (`vim.api.keyset.option?`) Optional parameters
                  • buf: Buffer number. Used for setting buffer local option.
                  • dry_run: (`boolean?`, default: false) If true, then the
                    option value won't be set.
@@ -4275,7 +4275,7 @@ nvim_win_resize({win}, {width}, {height}, {opts})          *nvim_win_resize()*
       • {win}     (`integer`) |window-ID|, or 0 for current window
       • {width}   (`integer`) New width (columns), or -1 for "no change".
       • {height}  (`integer`) New height (rows), or -1 for "no change".
-      • {opts}    (`vim.api.keyset.win_resize`) Optional parameters.
+      • {opts}    (`vim.api.keyset.win_resize?`) Optional parameters.
                   • anchor: Edge that stays fixed while the opposite edge
                     moves; the neighbor on the moving side is resized first.
                     One of:
@@ -4350,7 +4350,7 @@ nvim_win_text_height({win}, {opts})                   *nvim_win_text_height()*
 
     Parameters: ~
       • {win}   (`integer`) |window-ID|, or 0 for current window.
-      • {opts}  (`vim.api.keyset.win_text_height`) Optional parameters:
+      • {opts}  (`vim.api.keyset.win_text_height?`) Optional parameters:
                 • end_row: Ending line index, 0-based inclusive. When omitted
                   end at the very bottom.
                 • end_vcol: Ending virtual column index on "end_row", 0-based
diff --git a/runtime/lua/vim/_meta/api.gen.lua b/runtime/lua/vim/_meta/api.gen.lua
index ac8121af5e..d5208ce596 100644
--- a/runtime/lua/vim/_meta/api.gen.lua
+++ b/runtime/lua/vim/_meta/api.gen.lua
@@ -38,7 +38,7 @@ function vim.api.nvim__cmdwin_set(type, buf) end
 --- returns the window and buffer ids, or empty dict if not shown.
 ---
 --- @param index integer Completion candidate index
---- @param opts vim.api.keyset.complete_set Optional parameters.
+--- @param opts vim.api.keyset.complete_set? Optional parameters.
 --- - info: (string) info text.
 --- @return table<string,number> # Dict containing these keys:
 --- - winid: (number) floating window id
@@ -56,7 +56,7 @@ function vim.api.nvim__get_lib_dir() end
 ---
 --- @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
+--- @param opts vim.api.keyset.runtime? is_lua: only search Lua subdirs
 --- @return string[] # list of absolute paths to the found files
 function vim.api.nvim__get_runtime(pat, all, opts) end
 
@@ -132,7 +132,7 @@ function vim.api.nvim__ns_get(ns_id) end
 --- Set some properties for namespace
 ---
 --- @param ns_id integer Namespace
---- @param opts vim.api.keyset.ns_opts Optional parameters to set:
+--- @param opts vim.api.keyset.ns_opts? Optional parameters to set:
 --- - wins: a list of windows to be scoped in
 function vim.api.nvim__ns_set(ns_id, opts) end
 
@@ -142,7 +142,7 @@ function vim.api.nvim__ns_set(ns_id, opts) end
 ---
 ---
 --- @see `:help :redraw`
---- @param opts vim.api.keyset.redraw Optional parameters.
+--- @param opts vim.api.keyset.redraw? Optional parameters.
 --- - buf: Target a specific buffer number as described below.
 --- - cursor: Immediately update cursor position on the screen in
 ---   `win` or the current window.
@@ -224,7 +224,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
 --- whole buffer: first notification will be `nvim_buf_lines_event`.
 --- Else the first notification will be `nvim_buf_changedtick_event`.
 --- Not for Lua callbacks.
---- @param opts vim.api.keyset.buf_attach Optional parameters.
+--- @param opts vim.api.keyset.buf_attach? Optional parameters.
 --- - on_bytes: Called on granular changes (compared to on_lines). Not called on buffer
 ---   reload (`:checktime`, `:edit`, …), see `on_reload:`. Return a [lua-truthy] value
 ---   to detach. Args:
@@ -317,7 +317,7 @@ function vim.api.nvim_buf_clear_namespace(buf, ns_id, line_start, line_end) end
 --- @param buf integer Buffer id, or 0 for current buffer.
 --- @param name string
 --- @param cmd any
---- @param opts vim.api.keyset.user_command
+--- @param opts vim.api.keyset.user_command?
 function vim.api.nvim_buf_create_user_command(buf, name, cmd, opts) end
 
 --- Removes an `extmark`.
@@ -374,7 +374,7 @@ function vim.api.nvim_buf_del_var(buf, name) end
 --- ```
 ---
 --- @param buf integer Buffer id, or 0 for current buffer
---- @param opts vim.api.keyset.buf_delete Optional parameters. Keys:
+--- @param opts vim.api.keyset.buf_delete? Optional parameters. Keys:
 --- - force:  Force deletion, ignore unsaved changes.
 --- - unload: Unloaded only (`:bunload`), do not delete.
 function vim.api.nvim_buf_delete(buf, opts) end
@@ -388,7 +388,7 @@ function vim.api.nvim_buf_get_changedtick(buf) end
 --- Gets a map of buffer-local `user-commands`.
 ---
 --- @param buf integer Buffer id, or 0 for current buffer
---- @param opts vim.api.keyset.get_commands Optional parameters. Currently not used.
+--- @param opts vim.api.keyset.get_commands? Optional parameters. Currently not used.
 --- @return vim.api.keyset.command_info # Map of maps describing commands.
 function vim.api.nvim_buf_get_commands(buf, opts) end
 
@@ -397,7 +397,7 @@ function vim.api.nvim_buf_get_commands(buf, opts) end
 --- @param buf integer Buffer id, or 0 for current buffer
 --- @param ns_id integer Namespace id from `nvim_create_namespace()`
 --- @param id integer Extmark id
---- @param opts vim.api.keyset.get_extmark Optional parameters. Keys:
+--- @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 [integer, integer, vim.api.keyset.extmark_details?] # 0-indexed (row, col, details?) tuple or empty list () if extmark id was absent.  The
@@ -458,7 +458,7 @@ function vim.api.nvim_buf_get_extmark_by_id(buf, ns_id, id, opts) end
 --- (whose position defines the bound). `api-indexing`
 --- @param end_ any End of range (inclusive): a 0-indexed (row, col) or valid
 --- extmark id (whose position defines the bound). `api-indexing`
---- @param opts vim.api.keyset.get_extmarks Optional parameters. Keys:
+--- @param opts vim.api.keyset.get_extmarks? Optional parameters. Keys:
 --- - details: Whether to include the details dict
 --- - hl_name: Whether to include highlight group name instead of id, true if omitted
 --- - limit:  Maximum number of marks to return
@@ -556,7 +556,7 @@ function vim.api.nvim_buf_get_option(buffer, name) end
 --- @param start_col integer Starting column (byte offset) on first line
 --- @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.
+--- @param opts vim.api.keyset.empty? Optional parameters. Currently unused.
 --- @return string[] # Array of lines, or empty array for unloaded buffer.
 function vim.api.nvim_buf_get_text(buf, start_row, start_col, end_row, end_col, opts) end
 
@@ -611,7 +611,7 @@ function vim.api.nvim_buf_line_count(buf) end
 --- @param ns_id integer Namespace id from `nvim_create_namespace()`
 --- @param line integer Line where to place the mark, 0-based. `api-indexing`
 --- @param col integer Column where to place the mark, 0-based. `api-indexing`
---- @param opts vim.api.keyset.set_extmark Optional parameters:
+--- @param opts vim.api.keyset.set_extmark? Optional parameters:
 --- - conceal: (boolean|string)
 ---     - string: Single char or empty string, enables conceal similar to `:syn-conceal`.
 ---       Non-empty char is used as `:syn-cchar`. Highlighted with "hl_group" if
@@ -711,7 +711,7 @@ function vim.api.nvim_buf_set_extmark(buf, ns_id, line, col, opts) end
 --- @param mode string
 --- @param lhs string
 --- @param rhs string
---- @param opts vim.api.keyset.keymap
+--- @param opts vim.api.keyset.keymap?
 function vim.api.nvim_buf_set_keymap(buf, mode, lhs, rhs, opts) end
 
 --- Sets (replaces) a line-range in the buffer.
@@ -750,7 +750,7 @@ function vim.api.nvim_buf_set_lines(buf, start, end_, strict_indexing, replaceme
 --- @param name string Mark name
 --- @param line integer Line number
 --- @param col integer Column/row number
---- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
+--- @param opts vim.api.keyset.empty? Optional parameters. Reserved for future use.
 --- @return boolean # true if the mark was set, else false.
 function vim.api.nvim_buf_set_mark(buf, name, line, col, opts) end
 
@@ -804,7 +804,7 @@ function vim.api.nvim_buf_set_var(buf, name, value) end
 --- @param src_id integer
 --- @param line integer
 --- @param chunks any[]
---- @param opts vim.api.keyset.empty
+--- @param opts vim.api.keyset.empty?
 --- @return integer
 function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) end
 
@@ -843,7 +843,7 @@ function vim.api.nvim_chan_send(chan, data) end
 
 --- Clears all autocommands matching the {opts} query. To delete autocmds see `nvim_del_autocmd()`.
 ---
---- @param opts vim.api.keyset.clear_autocmds Optional parameters:
+--- @param opts vim.api.keyset.clear_autocmds? Optional parameters:
 --- - buf: (`integer?`) Select `autocmd-buflocal` autocommands. Not allowed with {pattern}.
 --- - event: (`vim.api.keyset.events|vim.api.keyset.events[]?`)
 ---   Examples:
@@ -883,7 +883,7 @@ function vim.api.nvim_clear_autocmds(opts) end
 --- @param cmd vim.api.keyset.cmd Command to execute, a Dict with the same structure as the return value of
 --- `nvim_parse_cmd()` (except "addr", "nargs" and "nextcmd" are ignored).
 --- All keys except "cmd" are optional.
---- @param opts vim.api.keyset.cmd_opts Optional parameters.
+--- @param opts vim.api.keyset.cmd_opts? Optional parameters.
 --- - output: (boolean, default false) Whether to return command output.
 --- @return string # Command output (non-error, non-shell |:!|) if `output` is true, else empty string.
 function vim.api.nvim_cmd(cmd, opts) end
@@ -916,7 +916,7 @@ function vim.api.nvim_command_output(command) end
 ---
 --- @see `:help autocmd-groups`
 --- @param name string Group name
---- @param opts vim.api.keyset.create_augroup Optional parameters:
+--- @param opts vim.api.keyset.create_augroup? Optional parameters:
 --- - clear (`boolean?`, default: true) Clear existing commands in the group `autocmd-groups`.
 --- @return integer # Group id.
 function vim.api.nvim_create_augroup(name, opts) end
@@ -954,7 +954,7 @@ function vim.api.nvim_create_augroup(name, opts) end
 --- @see `:help autocommand`
 --- @see vim.api.nvim_del_autocmd
 --- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) that will trigger the handler (`callback` or `command`).
---- @param opts vim.api.keyset.create_autocmd Options dict:
+--- @param opts vim.api.keyset.create_autocmd? Options dict:
 --- - buf (`integer?`) Buffer id for buffer-local autocommands `autocmd-buflocal`.
 ---   Not allowed with {pattern}.
 --- - callback (`function|string?`) Lua function (or Vimscript function name, if string)
@@ -1025,7 +1025,7 @@ function vim.api.nvim_create_namespace(name) end
 --- - range: (number) Number of items in the command range: 0, 1, or 2. [<range>]
 --- - reg: (string) Register name, if any. [<reg>]
 --- - smods: (table) Command modifiers (structured), same as "mods" in `nvim_parse_cmd()`.
---- @param opts vim.api.keyset.user_command Optional flags:
+--- @param opts vim.api.keyset.user_command? Optional flags:
 --- - `addr` `:command-addr`
 --- - `complete` `:command-complete` command or function `:command-completion-customlist`.
 --- - `count` `:command-count`
@@ -1112,7 +1112,7 @@ function vim.api.nvim_del_var(name) end
 --- @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.
+--- @param opts vim.api.keyset.echo_opts? Optional parameters.
 --- - data (`table?`) Dict of arbitrary data, available in `Progress` `event-data`.
 --- - err (`boolean?`)  Treat the message like `:echoerr`. Sets `hl_group` to `hl-ErrorMsg` by default.
 --- - id (`integer|string?`) Message-id returned by a previous `nvim_echo` call, or
@@ -1153,7 +1153,7 @@ function vim.api.nvim_eval(expr) end
 --- Evaluates statusline string.
 ---
 --- @param str string Statusline string (see 'statusline').
---- @param opts vim.api.keyset.eval_statusline Optional parameters.
+--- @param opts vim.api.keyset.eval_statusline? Optional parameters.
 --- - fillchar: (string) Character to fill blank spaces in the statusline (see
 ---                      'fillchars'). Treated as single-width even if it isn't.
 --- - highlights: (boolean) Return highlight information.
@@ -1194,7 +1194,7 @@ function vim.api.nvim_exec(src, output) end
 --- @see vim.api.nvim_command
 --- @see vim.api.nvim_cmd
 --- @param src string Vimscript code
---- @param opts vim.api.keyset.exec_opts Optional parameters.
+--- @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> # Dict containing information about execution, with these keys:
@@ -1205,7 +1205,7 @@ function vim.api.nvim_exec2(src, opts) end
 ---
 --- @see `:help :doautocmd`
 --- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) to execute.
---- @param opts vim.api.keyset.exec_autocmds Optional filters:
+--- @param opts vim.api.keyset.exec_autocmds? Optional filters:
 --- - buf (`integer?`) Buffer where the event is applied. `autocmd-buflocal` Not allowed with {pattern}.
 --- - data (`any`): Arbitrary data passed to the callback. See `nvim_create_autocmd()`.
 --- - group (`string|integer?`) Group name or id to match against. `autocmd-groups`.
@@ -1270,7 +1270,7 @@ function vim.api.nvim_get_all_options_info() end
 --- })
 --- ```
 ---
---- @param opts vim.api.keyset.get_autocmds Dict with at least one of these keys:
+--- @param opts vim.api.keyset.get_autocmds? Dict with at least one of these keys:
 --- - buf: (`integer[]|integer?`) Buffer id or list of buffer ids, for buffer-local autocommands
 ---   `autocmd-buflocal`. Not allowed with {pattern}.
 --- - event: (`vim.api.keyset.events|vim.api.keyset.events[]?`) Event(s) to match `autocmd-events`.
@@ -1347,14 +1347,14 @@ 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
+--- @param opts vim.api.keyset.get_commands? Optional parameters. Currently only supports
 --- {"builtin":false}
 --- @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.
 ---
---- @param opts vim.api.keyset.context Optional parameters.
+--- @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> # map of global |context|.
@@ -1389,7 +1389,7 @@ function vim.api.nvim_get_current_win() end
 ---
 --- @param ns_id integer Get highlight groups for namespace ns_id `nvim_get_namespaces()`.
 --- Use 0 to get global highlight groups `:highlight`.
---- @param opts vim.api.keyset.get_highlight Options dict:
+--- @param opts vim.api.keyset.get_highlight? Options dict:
 --- - create: (boolean, default true) When highlight group doesn't exist create it.
 --- - id: (integer) Get a highlight definition by id.
 --- - link: (boolean, default true) Show linked group name instead of effective definition `:hi-link`.
@@ -1421,7 +1421,7 @@ function vim.api.nvim_get_hl_id_by_name(name) end
 
 --- Gets the active highlight namespace.
 ---
---- @param opts vim.api.keyset.get_ns Optional parameters
+--- @param opts vim.api.keyset.get_ns? Optional parameters
 --- - winid: (number) `window-ID` for retrieving a window's 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
@@ -1448,7 +1448,7 @@ function vim.api.nvim_get_keymap(mode) end
 --- @see vim.api.nvim_buf_set_mark
 --- @see vim.api.nvim_del_mark
 --- @param name string Mark name
---- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
+--- @param opts vim.api.keyset.empty? Optional parameters. Reserved for future use.
 --- @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
@@ -1499,7 +1499,7 @@ function vim.api.nvim_get_option_info(name) end
 --- explicitly specifying {scope} in the {opts} table.
 ---
 --- @param name string Option name
---- @param opts vim.api.keyset.option Optional parameters
+--- @param opts vim.api.keyset.option? Optional parameters
 --- - buf: Buffer number. Used for getting buffer local options.
 ---        Implies {scope} is "local".
 --- - scope: One of "global" or "local". Analogous to
@@ -1514,7 +1514,7 @@ function vim.api.nvim_get_option_info2(name, opts) end
 --- buffer or window, unless "buf" or "win" is set in {opts}.
 ---
 --- @param name string Option name
---- @param opts vim.api.keyset.option Optional parameters
+--- @param opts vim.api.keyset.option? Optional parameters
 --- - buf: Buffer number. Used for getting buffer local options.
 ---        Implies {scope} is "local".
 --- - filetype: `filetype`. Used to get the default option for a
@@ -1713,7 +1713,7 @@ function vim.api.nvim_open_tabpage(buf, enter, config) end
 ---
 --- @param buf integer Buffer which displays the PTY output. The initial buffer contents (if any) will be
 --- written to the PTY.
---- @param opts vim.api.keyset.open_term Optional parameters.
+--- @param opts vim.api.keyset.open_term? Optional parameters.
 --- - force_crlf: (boolean, default true) Convert "\n" to "\r\n".
 --- - on_input: Lua callback for input sent, i e keypresses in terminal
 ---   mode. Note: keypresses are sent raw as they would be to the pty
@@ -1886,7 +1886,7 @@ function vim.api.nvim_out_write(str) end
 --- Doesn't check the validity of command arguments.
 ---
 --- @param str string Command line string to parse. Cannot contain "\n".
---- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
+--- @param opts vim.api.keyset.empty? Optional parameters. Reserved for future use.
 --- @return vim.api.keyset.cmd # Dict containing command information, with these keys:
 --- - cmd: (string) Command name.
 --- - range: (array) (optional) Command range ([<line1>] [<line2>]).
@@ -2092,7 +2092,7 @@ function vim.api.nvim_replace_termcodes(str, from_part, do_lt, special) end
 --- @param insert boolean For `ins-completion`, whether the selection should be inserted in the buffer.
 --- Ignored for `cmdline-completion`.
 --- @param finish boolean Finish the completion and dismiss the popup menu. Implies {insert}.
---- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
+--- @param opts vim.api.keyset.empty? Optional parameters. Reserved for future use.
 function vim.api.nvim_select_popupmenu_item(item, insert, finish, opts) end
 
 --- Sets the current window's buffer to `buf`.
@@ -2151,7 +2151,7 @@ function vim.api.nvim_set_current_win(win) end
 --- Note: Callbacks will not run for `window-hidden`, as they are not redrawn.
 ---
 --- @param ns_id integer Namespace id from `nvim_create_namespace()`
---- @param opts vim.api.keyset.set_decoration_provider Table of callbacks:
+--- @param opts vim.api.keyset.set_decoration_provider? Table of callbacks:
 --- - on_buf: called for each buffer being redrawn (once per edit,
 ---   before window callbacks)
 ---   ```
@@ -2283,7 +2283,7 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end
 --- "ia", "ca" or "!a" for abbreviation in Insert mode, Cmdline mode, or both, respectively
 --- @param lhs string Left-hand-side `{lhs}` of the mapping.
 --- @param rhs string Right-hand-side `{rhs}` of the mapping.
---- @param opts vim.api.keyset.keymap Optional parameters map: Accepts all `:map-arguments` as keys except [<buffer>],
+--- @param opts vim.api.keyset.keymap? Optional parameters map: Accepts all `:map-arguments` as keys except [<buffer>],
 --- values are booleans (default false). Also:
 --- - "callback" Lua function called in place of {rhs}.
 --- - "desc" human-readable description.
@@ -2306,7 +2306,7 @@ function vim.api.nvim_set_option(name, value) end
 ---
 --- @param name string Option name
 --- @param value any New option value
---- @param opts vim.api.keyset.option Optional parameters
+--- @param opts vim.api.keyset.option? Optional parameters
 --- - buf: Buffer number. Used for setting buffer local option.
 --- - dry_run: (`boolean?`, default: false) If true, then the
 ---   option value won't be set.
@@ -2518,7 +2518,7 @@ function vim.api.nvim_win_is_valid(win) end
 --- @param win integer `window-ID`, or 0 for current window
 --- @param width integer New width (columns), or -1 for "no change".
 --- @param height integer New height (rows), or -1 for "no change".
---- @param opts vim.api.keyset.win_resize Optional parameters.
+--- @param opts vim.api.keyset.win_resize? Optional parameters.
 --- - anchor: Edge that stays fixed while the opposite edge moves; the
 ---   neighbor on the moving side is resized first. One of:
 ---   - "top" (default) or "bottom"
@@ -2605,7 +2605,7 @@ function vim.api.nvim_win_set_width(win, width) end
 ---
 --- @see `:help virtcol()` for text width.
 --- @param win integer `window-ID`, or 0 for current window.
---- @param opts vim.api.keyset.win_text_height Optional parameters:
+--- @param opts vim.api.keyset.win_text_height? Optional parameters:
 --- - end_row: Ending line index, 0-based inclusive.
 ---            When omitted end at the very bottom.
 --- - end_vcol: Ending virtual column index on "end_row",
diff --git a/src/gen/c_grammar.lua b/src/gen/c_grammar.lua
index cb0908497b..bff14a2ffe 100644
--- a/src/gen/c_grammar.lua
+++ b/src/gen/c_grammar.lua
@@ -354,7 +354,20 @@ if arg[1] == '--test' then
   end
 end
 
+--- Index of the `opts` parameter, which starts optional parameters.
+--- @param fn_params [string,string][] Raw `{type, name}` pairs of a parsed API function.
+--- @return integer? opts_idx 1-based index of `opts`, or nil.
+local function opts_index(fn_params)
+  for i = 1, #fn_params do
+    local c = typed_container:match(fn_params[i][1])
+    if fn_params[i][2] == 'opts' and c and c[1] == 'Dict' then
+      return i
+    end
+  end
+end
+
 return {
   grammar = grammar --[[@as nvim.c_grammar]],
   typed_container = typed_container,
+  opts_index = opts_index,
 }
diff --git a/src/gen/cdoc_parser.lua b/src/gen/cdoc_parser.lua
index 493fbbf928..f15ea52a23 100644
--- a/src/gen/cdoc_parser.lua
+++ b/src/gen/cdoc_parser.lua
@@ -192,6 +192,17 @@ local function process_proto(item, state)
       table.remove(cur_obj.params, i)
     end
   end
+
+  -- HACK: Mark optional params (:help api-contract) with "?" so docs render them as optional.
+  if c_grammar.opts_index(item.parameters) then
+    local optional = false
+    for _, p in ipairs(cur_obj.params) do
+      optional = optional or p.name == 'opts'
+      if optional and not p.type:match('%?$') then
+        p.type = p.type .. '?'
+      end
+    end
+  end
 end
 
 local M = {}
diff --git a/src/gen/gen_api_dispatch.lua b/src/gen/gen_api_dispatch.lua
index 990f6f0a01..731a9a0097 100644
--- a/src/gen/gen_api_dispatch.lua
+++ b/src/gen/gen_api_dispatch.lua
@@ -118,12 +118,7 @@ local function add_function(fn)
       fn.parameters[#fn.parameters] = nil
     end
     -- `opts` (a KeyDict) and every parameter following it are optional: clients may omit them.
-    for k = 1, #fn.parameters do
-      if fn.parameters[k][2] == 'opts' and real_type(fn.parameters[k][1]):match('^KeyDict_') then
-        fn.opts_idx = k
-        break
-      end
-    end
+    fn.opts_idx = c_grammar.opts_index(fn.parameters)
     -- Omitted optional param is zero-initialized, which assumes Dict/Array.
     if fn.opts_idx then
       for k = fn.opts_idx + 1, #fn.parameters do