Merge #37830 docs

3 files changed, 38 insertions, 37 deletions

diff --git a/runtime/lua/vim/_core/defaults.lua b/runtime/lua/vim/_core/defaults.lua
index e923e8934c..9b9ab01b52 100644
--- a/runtime/lua/vim/_core/defaults.lua
+++ b/runtime/lua/vim/_core/defaults.lua
@@ -445,15 +445,15 @@ do
     end, { expr = true, desc = 'Add empty line below cursor' })
   end
 
-  --- incremental treesitter selection mappings (+ lsp fallback)
+  --- "Incremental selection" mappings (treesitter + LSP fallback).
   do
     vim.keymap.set({ 'x' }, '[n', function()
       require 'vim.treesitter._select'.select_prev(vim.v.count1)
-    end, { desc = 'Select previous treesitter node' })
+    end, { desc = 'Select previous node' })
 
     vim.keymap.set({ 'x' }, ']n', function()
       require 'vim.treesitter._select'.select_next(vim.v.count1)
-    end, { desc = 'Select next treesitter node' })
+    end, { desc = 'Select next node' })
 
     vim.keymap.set({ 'x', 'o' }, 'an', function()
       if vim.treesitter.get_parser(nil, nil, { error = false }) then
@@ -461,7 +461,7 @@ do
       else
         vim.lsp.buf.selection_range(vim.v.count1)
       end
-    end, { desc = 'Select parent treesitter node or outer incremental lsp selections' })
+    end, { desc = 'Select parent (outer) node' })
 
     vim.keymap.set({ 'x', 'o' }, 'in', function()
       if vim.treesitter.get_parser(nil, nil, { error = false }) then
@@ -469,7 +469,7 @@ do
       else
         vim.lsp.buf.selection_range(-vim.v.count1)
       end
-    end, { desc = 'Select child treesitter node or inner incremental lsp selections' })
+    end, { desc = 'Select child (inner) node' })
   end
 end
 
diff --git a/runtime/lua/vim/_core/shared.lua b/runtime/lua/vim/_core/shared.lua
index 1f01b70f2a..da50338d01 100644
--- a/runtime/lua/vim/_core/shared.lua
+++ b/runtime/lua/vim/_core/shared.lua
@@ -360,7 +360,7 @@ local function key_fn(v, key)
   return key and key(v) or v
 end
 
---- Removes duplicate values from a list-like table in-place.
+--- Removes duplicate values from a |lua-list| in-place.
 ---
 --- Only the first occurrence of each value is kept.
 --- The operation is performed in-place and the input table is modified.
@@ -383,6 +383,7 @@ end
 --- -- t is now { {id=1}, {id=2} }
 --- ```
 ---
+--- @since 14
 --- @generic T
 --- @param t T[]
 --- @param key? fun(x: T): any Optional hash function to determine uniqueness of values
@@ -482,8 +483,8 @@ local function upper_bound(t, val, lo, hi, key)
   return lo
 end
 
---- Search for a position in a sorted list {t}
---- where {val} can be inserted while keeping the list sorted.
+--- Search for a position in a sorted |lua-list| {t} where {val} can be inserted while keeping the
+--- list sorted.
 ---
 --- Use {bound} to determine whether to return the first or the last position,
 --- defaults to "lower", i.e., the first position.
@@ -514,6 +515,7 @@ end
 ---   print(t[i]) -- { 3, 3, 3 }
 --- end
 --- ```
+---@since 14
 ---@generic T
 ---@param t T[] A comparable list.
 ---@param val T The value to search.
diff --git a/runtime/lua/vim/_core/ui2.lua b/runtime/lua/vim/_core/ui2.lua
index debd1feac5..1414eb75e7 100644
--- a/runtime/lua/vim/_core/ui2.lua
+++ b/runtime/lua/vim/_core/ui2.lua
@@ -1,38 +1,37 @@
 --- @brief
 ---
----WARNING: This is an experimental interface intended to replace the message
----grid in the TUI.
+--- WARNING: This is an experimental feature intended to replace the builtin message + cmdline
+--- presentation layer.
 ---
----To enable the experimental UI (default opts shown):
----```lua
----require('vim._core.ui2').enable({
----  enable = true, -- Whether to enable or disable the UI.
----  msg = { -- Options related to the message module.
----    ---@type 'cmd'|'msg' Default message target, either in the
----    ---cmdline or in a separate ephemeral message window.
----    ---@type string|table<string, 'cmd'|'msg'|'pager'> Default message target
----    or table mapping |ui-messages| kinds and triggers to a target.
----    targets = 'cmd',
----    timeout = 4000, -- Time a message is visible in the message window.
----  },
----})
----```
+--- To enable this feature (default opts shown):
+--- ```lua
+--- require('vim._core.ui2').enable({
+---   enable = true, -- Whether to enable or disable the UI.
+---   msg = { -- Options related to the message module.
+---     ---@type 'cmd'|'msg' Default message target, either in the
+---     ---cmdline or in a separate ephemeral message window.
+---     ---@type string|table<string, 'cmd'|'msg'|'pager'> Default message target
+---     ---or table mapping |ui-messages| kinds and triggers to a target.
+---     targets = 'cmd',
+---     timeout = 4000, -- Time a message is visible in the message window.
+---   },
+--- })
+--- ```
 ---
----There are four separate window types used by this interface:
----- "cmd": The cmdline window; also used for 'showcmd', 'showmode', 'ruler', and
----  messages if 'cmdheight' > 0.
----- "msg": The message window; used for messages when 'cmdheight' == 0.
----- "pager": The pager window; used for |:messages| and certain messages
----   that should be shown in full.
----- "dialog": The dialog window; used for prompt messages that expect user input.
+--- There are four special windows/buffers for presenting messages and cmdline:
+--- - "cmd": Cmdline. Also used for 'showcmd', 'showmode', 'ruler', and messages if 'cmdheight' > 0.
+--- - "msg": Message window, shows messages when 'cmdheight' == 0.
+--- - "pager": Pager window, shows |:messages| and certain messages that are never "collapsed".
+--- - "dialog": Dialog window, shows modal prompts that expect user input.
 ---
----These four windows are assigned the "cmd", "msg", "pager" and "dialog"
----'filetype' respectively. Use a |FileType| autocommand to configure any local
----options for these windows and their respective buffers.
+--- The buffer 'filetype' is to the above-listed id ("cmd", "msg", …). Handle the |FileType| event
+--- to configure any local options for these windows and their respective buffers.
 ---
----Rather than a |hit-enter-prompt|, messages shown in the cmdline area that do
----not fit are appended with a `[+x]` "spill" indicator, where `x` indicates the
----spilled lines. To see the full message, the |g<| command can be used.
+--- Unlike the legacy |hit-enter| prompt, messages that overflow the cmdline area are instead
+--- "collapsed", followed by a `[+x]` "spill" indicator, where `x` indicates the spilled lines. To
+--- see the full messages, do either:
+--- - ENTER immediately after a message from interactive |:| cmdline.
+--- - |g<| at any time.
 
 local api = vim.api
 local M = {