From 237bb9cb59d00264cdf21f5352fda7515c1b2e05 Mon Sep 17 00:00:00 2001 From: Yi Ming Date: Wed, 18 Jun 2025 18:20:18 +0800 Subject: [PATCH] docs(ui): type annotations for options #33983 --- runtime/doc/lua.txt | 24 +++++++------- runtime/lua/vim/ui.lua | 74 ++++++++++++++++++++++++++---------------- 2 files changed, 58 insertions(+), 40 deletions(-) diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 45063ddc54..8a1135bffc 100644 --- a/runtime/doc/lua.txt +++ b/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 - • default (string|nil) Default reply to the input - • completion (string|nil) Specifies type of completion + • {prompt}? (`string`) Text of the prompt + • {default}? (`string`) Default reply to the input + • {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 - highlighting user inputs. - • {on_confirm} (`fun(input:string?)`) Called once the user confirms or + • {highlight}? (`function`) Function that will be used + for highlighting user inputs. + • {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 - • cmd string[]|nil Command used to open the path or URL. + • {opt} (`table?`) Options + • {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 - an individual item from `items`. Defaults to + • {format_item}? (`fun(item: any):string`) Function 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. diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua index 4a5ffd73e6..a3f1a7a3ad 100644 --- a/runtime/lua/vim/ui.lua +++ b/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 ---- - 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 opts vim.ui.select.Opts Additional options ---@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()| ---- - prompt (string|nil) ---- 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) +---@param opts? vim.ui.input.Opts Additional options. See |input()| +---@param 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 @@ -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 ---- - cmd string[]|nil Command used to open the path or URL. +---@param opt? vim.ui.open.Opts Options --- ---@return vim.SystemObj|nil # Command object, or nil if not found. ---@return nil|string # Error message on failure, or nil on success.