docs: misc, options, pos/range

8 files changed, 45 insertions, 59 deletions

diff --git a/runtime/lua/vim/_core/shared.lua b/runtime/lua/vim/_core/shared.lua
index 0965ceac65..3eebfa4a39 100644
--- a/runtime/lua/vim/_core/shared.lua
+++ b/runtime/lua/vim/_core/shared.lua
@@ -311,7 +311,8 @@ end
 --- @class vim.tbl_contains.Opts
 --- @inlinedoc
 ---
---- `value` is a function reference to be checked (default false)
+--- `value` is a function reference to be checked
+--- (default: false)
 --- @field predicate? boolean
 
 --- Checks if a table contains a given value, specified either directly or via
@@ -1223,27 +1224,13 @@ do
   ---       end
   ---     ```
   ---
-  --- 2. `vim.validate(spec)` (deprecated)
-  ---     where `spec` is of type
+  --- 2. `vim.validate(spec)` (DEPRECATED) where `spec` is of type
   ---    `table<string,[value:any, validator: vim.validate.Validator, optional_or_msg? : boolean|string]>)`
   ---
   ---     Validates a argument specification.
   ---     Specs are evaluated in alphanumeric order, until the first failure.
   ---
-  ---     Example:
-  ---
-  ---     ```lua
-  ---       function user.new(name, age, hobbies)
-  ---         vim.validate{
-  ---           name={name, 'string'},
-  ---           age={age, 'number'},
-  ---           hobbies={hobbies, 'table'},
-  ---         }
-  ---         -- ...
-  ---       end
-  ---     ```
-  ---
-  --- Examples with explicit argument values (can be run directly):
+  --- Examples:
   ---
   --- ```lua
   --- vim.validate('arg1', {'foo'}, 'table')
@@ -1256,15 +1243,11 @@ do
   ---
   --- vim.validate('arg1', 3, function(a) return (a % 2) == 0 end, 'even number')
   ---    --> error('arg1: expected even number, got 3')
-  --- ```
-  ---
-  --- If multiple types are valid they can be given as a list.
   ---
-  --- ```lua
+  --- -- If multiple types are valid they can be given as a list:
   --- vim.validate('arg1', {'foo'}, {'table', 'string'})
   --- vim.validate('arg2', 'foo', {'table', 'string'})
   --- -- NOP (success)
-  ---
   --- vim.validate('arg1', 1, {'string', 'table'})
   --- -- error('arg1: expected string|table, got number')
   --- ```
@@ -1280,7 +1263,7 @@ do
   ---     `'thread'`, `'userdata'`.
   ---   - (`fun(val:any): boolean, string?`) A function that returns a boolean and an optional
   ---     string message.
-  --- @param optional? boolean Parameter is optional (may be omitted or nil)
+  --- @param optional? boolean (default: false) Parameter is optional (may be omitted or nil)
   --- @param message? string message when validation fails
   --- @overload fun(name: string, val: any, validator: vim.validate.Validator, message: string)
   --- @overload fun(spec: table<string,[any, vim.validate.Validator, boolean|string]>)
diff --git a/runtime/lua/vim/_meta/api.gen.lua b/runtime/lua/vim/_meta/api.gen.lua
index e5648706da..c055b859bc 100644
--- a/runtime/lua/vim/_meta/api.gen.lua
+++ b/runtime/lua/vim/_meta/api.gen.lua
@@ -1852,8 +1852,7 @@ function vim.api.nvim_open_term(buf, opts) end
 ---     Value can be one of "left", "center", or "right".
 ---     Default is `"left"`.
 --- - height: Window height (in character cells). Minimum of 1.
---- - hide: If true the floating window will be hidden and the cursor will be invisible when
----         focused on it.
+--- - hide: Hides the floating window. `window-hidden`
 --- - mouse: Specify how this window interacts with mouse events.
 ---     Defaults to `focusable` value.
 ---     - If false, mouse events pass through this window.
@@ -2514,12 +2513,10 @@ function vim.api.nvim_win_get_var(win, name) end
 --- @return integer # Width as a count of columns
 function vim.api.nvim_win_get_width(win) end
 
---- Closes the window and hide the buffer it contains (like `:hide` with a
---- `window-ID`).
+--- Closes the window and hides the buffer it contains (like `:hide` with a `window-ID`; unrelated
+--- to the `hide` flag of `nvim_open_win()`, `nvim_win_get_config()`).
 ---
---- Like `:hide` the buffer becomes hidden unless another window is editing it,
---- or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to `:close` or
---- `nvim_win_close()`, which will close the buffer.
+--- Compare `:close` and `nvim_win_close()`, which close the buffer instead of hiding it.
 ---
 --- @param win integer `window-ID`, or 0 for current window
 function vim.api.nvim_win_hide(win) end
diff --git a/runtime/lua/vim/_meta/options.gen.lua b/runtime/lua/vim/_meta/options.gen.lua
index fefc7d7eb7..520abbd8a6 100644
--- a/runtime/lua/vim/_meta/options.gen.lua
+++ b/runtime/lua/vim/_meta/options.gen.lua
@@ -652,14 +652,15 @@ vim.bo.buflisted = vim.o.buflisted
 vim.bo.bl = vim.bo.buflisted
 
 --- The value of this option specifies the type of a buffer:
----   <empty>	normal buffer
----   acwrite	buffer will always be written with `BufWriteCmd`s
----   help		help buffer (do not set this manually)
----   nofile	buffer is not related to a file, will not be written
----   nowrite	buffer will not be written
----   prompt	buffer where only the last section can be edited, for
+---   (empty)	Normal buffer.
+---   acwrite	Buffer will always be written with `BufWriteCmd`.
+---   help		Help buffer (do not set this manually).
+---   nofile	Buffer is not a file, will not be written.
+---   nowrite	Buffer represents a filepath (such as a directory),
+--- 		but will not be written.
+---   prompt	Buffer where only the last section can be edited, for
 --- 		use by plugins. `prompt-buffer`
----   quickfix	list of errors `:cwindow` or locations `:lwindow`
+---   quickfix	List of errors `:cwindow` or locations `:lwindow`
 ---   terminal	`terminal-emulator` buffer
 ---
 --- This option is used together with 'bufhidden' and 'swapfile' to
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index 06832c0b08..5e0c19018c 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -52,8 +52,9 @@ local M = vim._defer_require('vim.diagnostic', {
 
 --- [diagnostic-structure]()
 ---
---- Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based
---- rows and columns). |api-indexing|
+--- Diagnostics use |api-indexing| (i.e. 0-based rows and columns). See also |vim.pos| and
+--- |vim.range| to convert positions from other systems.
+---
 --- @class vim.Diagnostic : vim.Diagnostic.Set
 --- @field bufnr integer Buffer number
 --- @field end_lnum integer The final line of the diagnostic (0-indexed)
@@ -568,7 +569,7 @@ end
 --- Limit diagnostics to one or more namespaces.
 --- @field namespace? integer[]|integer
 ---
---- Limit diagnostics to those spanning the specified line number.
+--- Limit diagnostics to those spanning the specified line number (0-indexed, see |diagnostic-structure|).
 --- @field lnum? integer
 ---
 --- See |diagnostic-severity|.
diff --git a/runtime/lua/vim/hl.lua b/runtime/lua/vim/hl.lua
index f67a7a8b96..08307457b1 100644
--- a/runtime/lua/vim/hl.lua
+++ b/runtime/lua/vim/hl.lua
@@ -164,12 +164,12 @@ local events_ns = api.nvim_create_namespace('nvim.hl.events')
 --- ```
 ---
 --- @param opts table|nil Optional parameters
----              - event     (default vim.v.event) Event structure.
----              - higroup   (default "IncSearch") Highlight group for the text region.
----              - on_macro  (default false) Highlight during |macro| execution.
----              - on_visual (default true) Highlight during |Visual| mode.
----              - priority  (default |vim.hl.priorities|`.user`) Integer priority.
----              - timeout   (default 150) Time in ms before highlight is cleared.
+---              - event     (default: vim.v.event) Event structure.
+---              - higroup   (default: "IncSearch") Highlight group for the text region.
+---              - on_macro  (default: false) Highlight during |macro| execution.
+---              - on_visual (default: true) Highlight during |Visual| mode.
+---              - priority  (default: |vim.hl.priorities|`.user`) Integer priority.
+---              - timeout   (default: 150) Time in ms before highlight is cleared.
 function M.hl_op(opts)
   vim.validate('opts', opts, 'table', true)
   opts = opts or {}
diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index ade3c752d6..4b9a32ff8c 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/runtime/lua/vim/keymap.lua
@@ -16,7 +16,8 @@ local keymap = {}
 --- (Default: `false`)
 --- @field remap? boolean
 
---- Defines a |mapping| of |keycodes| to a function or keycodes.
+--- Defines a |mapping| of |keycodes| to a function or keycodes. If `lhs` is a list, defines
+--- a mapping for each (mode, lhs) pair.
 ---
 --- Examples:
 ---
@@ -43,6 +44,13 @@ local keymap = {}
 ---   local line2 = region[#region][1][2]
 ---   vim.print({ line1, line2 })
 --- end)
+---
+--- vim.keymap.set({ 'n', 'i' }, { 'a', 'b' }, '<cmd>echom localtime()<cr>')
+--- -- ... is the same as:
+--- vim.keymap.set('n', 'a', '<cmd>echom localtime()<cr>')
+--- vim.keymap.set('i', 'a', '<cmd>echom localtime()<cr>')
+--- vim.keymap.set('n', 'b', '<cmd>echom localtime()<cr>')
+--- vim.keymap.set('i', 'b', '<cmd>echom localtime()<cr>')
 --- ```
 ---
 ---@param modes string|string[] Mode "short-name" (see |nvim_set_keymap()|), or a list thereof.
@@ -112,12 +120,11 @@ end
 --- Remove a mapping from the given buffer. `0` for current.
 --- @field buf? integer
 
---- Remove an existing mapping.
+--- Removes a mapping, or removes each (mode, lhs) pair if `lhs` is a list.
 --- Examples:
 ---
 --- ```lua
 --- vim.keymap.del('n', 'lhs')
----
 --- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buf = 5 })
 --- ```
 ---
diff --git a/runtime/lua/vim/pos.lua b/runtime/lua/vim/pos.lua
index 15cc318ddd..599bd3ab33 100644
--- a/runtime/lua/vim/pos.lua
+++ b/runtime/lua/vim/pos.lua
@@ -10,10 +10,8 @@ local api = vim.api
 local validate = vim.validate
 local util = require('vim.pos._util')
 
---- Represents a well-defined position.
----
---- A |vim.Pos| object contains the {row} and {col} coordinates of a position.
---- To create a new |vim.Pos| object, call `vim.pos()`.
+--- Represents a buffer position based on [api-indexing] (0-indexed, end-exclusive ranges).
+--- Call `vim.pos()` to create a new `vim.Pos` by passing the {buf}, {row}, and {col} of a position.
 ---
 --- Example:
 --- ```lua
@@ -170,7 +168,7 @@ end
 --- Example:
 --- ```lua
 --- local cursor_pos = vim.api.nvim_win_get_cursor(0)
---- local pos = vim.pos.lsp(0, cursor_pos)
+--- local pos = vim.pos.cursor(0, cursor_pos)
 --- ```
 ---@param buf integer
 ---@param pos [integer, integer] (lnum, col) tuple
diff --git a/runtime/lua/vim/range.lua b/runtime/lua/vim/range.lua
index 489b41e2b3..e8dd7d8bb9 100644
--- a/runtime/lua/vim/range.lua
+++ b/runtime/lua/vim/range.lua
@@ -10,12 +10,11 @@ local validate = vim.validate
 local api = vim.api
 local util = require('vim.pos._util')
 
---- Represents a range. Call `vim.range()` to create a new range.
+--- Represents a range based on [api-indexing] (0-indexed, end-exclusive). Call `vim.range()` to
+--- create a new range by passing start and end positions (|vim.Pos|).
 ---
---- A range contains a start and end position (see |vim.Pos|). The end position is exclusive.
---- Positions must have the same optional fields.
----
---- May include optional fields that enable additional capabilities, such as format conversions.
+--- Both positions must have the same optional fields, which may enable additional capabilities
+--- (such as format conversions).
 ---
 --- Example:
 --- ```lua