docs(ui): type annotations for options #33983

runtime/doc/lua.txt

@@ -2598,15 +2598,15 @@ vim.ui.input({opts}, {on_confirm})                            *vim.ui.input()*
 
     Parameters: ~
       • {opts}        (`table?`) Additional options. See |input()|
-                      • prompt (string|nil) Text of the prompt
+                      • {prompt}? (`string`) Text of the prompt
-                      • default (string|nil) Default reply to the input
+                      • {default}? (`string`) Default reply to the input
-                      • completion (string|nil) Specifies type of completion
+                      • {completion}? (`string`) Specifies type of completion
                         supported for input. Supported types are the same that
                         can be supplied to a user-defined command using the
                         "-complete=" argument. See |:command-completion|
-                      • highlight (function) Function that will be used for
+                      • {highlight}? (`function`) Function that will be used
-                        highlighting user inputs.
+                        for highlighting user inputs.
-      • {on_confirm}  (`fun(input:string?)`) Called once the user confirms or
+      • {on_confirm}  (`fun(input?: string)`) Called once the user confirms or
                       abort the input. `input` is what the user typed (it
                       might be an empty string if nothing was entered), or
                       `nil` if the user aborted the dialog.
@@ -2635,8 +2635,8 @@ vim.ui.open({path}, {opt})                                     *vim.ui.open()*
 
     Parameters: ~
       • {path}  (`string`) Path or URL to open
-      • {opt}   (`{ cmd?: string[] }?`) Options
+      • {opt}   (`table?`) Options
-                • cmd string[]|nil Command used to open the path or URL.
+                • {cmd}? (`string[]`) Command used to open the path or URL.
 
     Return (multiple): ~
         (`vim.SystemObj?`) Command object, or nil if not found.
@@ -2667,12 +2667,12 @@ vim.ui.select({items}, {opts}, {on_choice})                  *vim.ui.select()*
     Parameters: ~
       • {items}      (`any[]`) Arbitrary items
       • {opts}       (`table`) Additional options
-                     • prompt (string|nil) Text of the prompt. Defaults to
+                     • {prompt}? (`string`) Text of the prompt. Defaults to
                        `Select one of:`
-                     • format_item (function item -> text) Function to format
+                     • {format_item}? (`fun(item: any):string`) Function to
-                       an individual item from `items`. Defaults to
+                       format an individual item from `items`. Defaults to
                        `tostring`.
-                     • kind (string|nil) Arbitrary hint string indicating the
+                     • {kind}? (`string`) Arbitrary hint string indicating the
                        item shape. Plugins reimplementing `vim.ui.select` may
                        wish to use this to infer the structure or semantics of
                        `items`, or the context in which select() was called.

runtime/lua/vim/ui.lua

@@ -1,5 +1,21 @@
 local M = {}
 
+---@class vim.ui.select.Opts
+---@inlinedoc
+---
+--- Text of the prompt. Defaults to `Select one of:`
+---@field prompt? string
+---
+--- Function to format an
+--- individual item from `items`. Defaults to `tostring`.
+---@field format_item? fun(item: any):string
+---
+--- Arbitrary hint string indicating the item shape.
+--- Plugins reimplementing `vim.ui.select` may wish to
+--- use this to infer the structure or semantics of
+--- `items`, or the context in which select() was called.
+---@field kind? string
+
 --- Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous)
 --- work until `on_choice`.
 ---
@@ -22,17 +38,7 @@ local M = {}
 ---
 ---@generic T
 ---@param items T[] Arbitrary items
----@param opts table Additional options
+---@param opts vim.ui.select.Opts Additional options
----     - prompt (string|nil)
----               Text of the prompt. Defaults to `Select one of:`
----     - format_item (function item -> text)
----               Function to format an
----               individual item from `items`. Defaults to `tostring`.
----     - kind (string|nil)
----               Arbitrary hint string indicating the item shape.
----               Plugins reimplementing `vim.ui.select` may wish to
----               use this to infer the structure or semantics of
----               `items`, or the context in which select() was called.
 ---@param on_choice fun(item: T|nil, idx: integer|nil)
 ---               Called once the user made a choice.
 ---               `idx` is the 1-based index of `item` within `items`.
@@ -56,6 +62,26 @@ function M.select(items, opts, on_choice)
   end
 end
 
+---@class vim.ui.input.Opts
+---@inlinedoc
+---
+---Text of the prompt
+---@field prompt? string
+---
+---Default reply to the input
+---@field default? string
+---
+---Specifies type of completion supported
+---for input. Supported types are the same
+---that can be supplied to a user-defined
+---command using the "-complete=" argument.
+---See |:command-completion|
+---@field completion? string
+---
+---Function that will be used for highlighting
+---user inputs.
+---@field highlight? function
+
 --- Prompts the user for input, allowing arbitrary (potentially asynchronous) work until
 --- `on_confirm`.
 ---
@@ -67,21 +93,8 @@ end
 --- end)
 --- ```
 ---
----@param opts table? Additional options. See |input()|
+---@param opts? vim.ui.input.Opts Additional options. See |input()|
----     - prompt (string|nil)
+---@param on_confirm fun(input?: string)
----               Text of the prompt
----     - default (string|nil)
----               Default reply to the input
----     - completion (string|nil)
----               Specifies type of completion supported
----               for input. Supported types are the same
----               that can be supplied to a user-defined
----               command using the "-complete=" argument.
----               See |:command-completion|
----     - highlight (function)
----               Function that will be used for highlighting
----               user inputs.
----@param on_confirm fun(input:string|nil)
 ---               Called once the user confirms or abort the input.
 ---               `input` is what the user typed (it might be
 ---               an empty string if nothing was entered), or
@@ -105,6 +118,12 @@ function M.input(opts, on_confirm)
   end
 end
 
+---@class vim.ui.open.Opts
+---@inlinedoc
+---
+--- Command used to open the path or URL.
+---@field cmd? string[]
+
 --- Opens `path` with the system default handler (macOS `open`, Windows `explorer.exe`, Linux
 --- `xdg-open`, …), or returns (but does not show) an error message on failure.
 ---
@@ -128,8 +147,7 @@ end
 --- ```
 ---
 ---@param path string Path or URL to open
----@param opt? { cmd?: string[] } Options
+---@param opt? vim.ui.open.Opts Options
----     - cmd string[]|nil Command used to open the path or URL.
 ---
 ---@return vim.SystemObj|nil # Command object, or nil if not found.
 ---@return nil|string # Error message on failure, or nil on success.