mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-06-15 16:23:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: misc, options, pos/range

Browse Source
This commit is contained in:
Justin M. Keyes
2026-05-20 11:47:24 +02:00
parent 88f3f0eeec
commit f5fae7aa5c
17 changed files with 120 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
runtime/lua/vim/_core/shared.lua
View File

@@ -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]>)

11
runtime/lua/vim/_meta/api.gen.lua generated
View File

@@ -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

15
runtime/lua/vim/_meta/options.gen.lua generated
View File

@@ -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

7
runtime/lua/vim/diagnostic.lua
View File

@@ -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|.

12
runtime/lua/vim/hl.lua
View File

@@ -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 {}

13
runtime/lua/vim/keymap.lua
View File

@@ -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 })
--- ```
---

8
runtime/lua/vim/pos.lua
View File

@@ -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

9
runtime/lua/vim/range.lua
View File

@@ -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