docs: vim.ui.select, misc

1 files changed, 21 insertions, 21 deletions

diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua
index bf4728c4d8..e4f18b9b3a 100644
--- a/runtime/lua/vim/ui.lua
+++ b/runtime/lua/vim/ui.lua
@@ -3,33 +3,35 @@ local M = {}
 ---@class vim.ui.select.Opts
 ---@inlinedoc
 ---
---- Text of the prompt.
---- (default: `Select one of:`)
+--- Prompt text.
+--- (default: `"Select one of:"`)
 ---@field prompt? string
 ---
---- Formats an individual item from `items`.
+--- Decides how to format items when displayed in the picker.
 --- (default: `tostring`)
 ---@field format_item? fun(item: any):string
 ---
---- Function to preview an individual item from `items`.
---- If missing, no special preview is used.
---- Should ensure a buffer with contents (text, highlighting) providing details about an item.
---- Should return a table with information that `vim.ui.select` implementations may
---- use to show the preview buffer in the way they see fit:
----     - {buf}? (`integer`) - buffer id with preview. If missing, no preview should be shown.
----     - {pos}? (`[integer, integer]`) - (1,0)-indexed tuple of where to position cursor
----       in the preview buffer. If missing, should be treated as `{ 1, 0 }`.
----@field preview_item? fun(item: any):table
+--- Decides how to preview an item by preparing a scratch buffer with the item details (including text, highlighting, etc.).
+--- When the picker decides to "preview" an item, it should call this function.
+--- Must return a table with these keys:
+---     - {buf}? (`integer`) Buffer containing the previewed item details, or nil if no preview should be shown.
+---     - {pos}? (`[integer, integer]`) Specifies the (1,0)-indexed cursor position in the preview buffer. If nil, should be treated as `{ 1, 0 }`.
+---     - {pos_end}? (`[integer, integer]`) Specifies the (1,0)-indexed (end-exclusive) end position of the preview range. If nil, no range is intended for a preview.
+---@field preview_item? fun(item: any):{buf?:integer, pos?:[integer,integer], pos_end?:[integer,integer]}
 ---
---- 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.
+--- Arbitrary hint string indicating the item shape. The picker 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`.
 ---
+--- Plugins may override `vim.ui.select` to provide a custom "picker" interface; they are expected
+--- to call the `format_item` and `preview_item` handlers (if any) provided by the caller. They may
+--- also use the `kind` hint (if provided by the caller) to decide how to handle some items.
+---
+--- Note: the default `vim.ui.select` currently doesn't support preview.
+---
 --- Example:
 ---
 --- ```lua
@@ -53,11 +55,9 @@ local M = {}
 ---
 ---@generic T
 ---@param items T[] Arbitrary items
----@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`.
----               `nil` if the user aborted the dialog.
+---@param opts vim.ui.select.Opts 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`, or `nil` if the user aborted the dialog.
 function M.select(items, opts, on_choice)
   vim.validate('items', items, 'table')
   vim.validate('on_choice', on_choice, 'function')