From f5fae7aa5cf1e599b2bbc0ef0ae6deccc8c0b3d5 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 20 May 2026 11:47:24 +0200 Subject: docs: misc, options, pos/range --- runtime/lua/vim/_core/shared.lua | 29 ++++++----------------------- runtime/lua/vim/_meta/api.gen.lua | 11 ++++------- runtime/lua/vim/_meta/options.gen.lua | 15 ++++++++------- runtime/lua/vim/diagnostic.lua | 7 ++++--- runtime/lua/vim/hl.lua | 12 ++++++------ runtime/lua/vim/keymap.lua | 13 ++++++++++--- runtime/lua/vim/pos.lua | 8 +++----- runtime/lua/vim/range.lua | 9 ++++----- 8 files changed, 45 insertions(+), 59 deletions(-) (limited to 'runtime/lua/vim') 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)` --- --- 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) 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: ---- 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' }, 'echom localtime()') +--- -- ... is the same as: +--- vim.keymap.set('n', 'a', 'echom localtime()') +--- vim.keymap.set('i', 'a', 'echom localtime()') +--- vim.keymap.set('n', 'b', 'echom localtime()') +--- vim.keymap.set('i', 'b', 'echom localtime()') --- ``` --- ---@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'}, '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 -- cgit