From 88f3f0eeec47d1edf62490861a29317cc5c81c89 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 28 May 2026 18:08:40 +0200 Subject: [PATCH 1/2] fix(health): sort "Active Features" by name --- runtime/lua/vim/lsp/health.lua | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/runtime/lua/vim/lsp/health.lua b/runtime/lua/vim/lsp/health.lua index 432ab81b9d..19362c86d0 100644 --- a/runtime/lua/vim/lsp/health.lua +++ b/runtime/lua/vim/lsp/health.lua @@ -52,10 +52,10 @@ local function check_active_features() return end - for _, Capability in pairs(vim.lsp._capability.all) do + for capname, capability in vim.spairs(vim.lsp._capability.all) do ---@type string[] local buf_infos = {} - for bufnr, instance in pairs(Capability.active) do + for bufnr, instance in pairs(capability.active) do local client_info = vim .iter(pairs(instance.client_state)) :map(function(client_id) @@ -63,7 +63,7 @@ local function check_active_features() if client then return string.format('%s (id: %d)', client.name, client.id) else - return string.format('unknow (id: %d)', client_id) + return string.format('unknown (id: %d)', client_id) end end) :join(', ') @@ -75,7 +75,7 @@ local function check_active_features() end report_info(table.concat({ - Capability.name, + capname, '- Active buffers:', vim.tbl_isempty(buf_infos) and ' (none)' or string.format(table.concat(buf_infos, '\n')), }, '\n')) From f5fae7aa5cf1e599b2bbc0ef0ae6deccc8c0b3d5 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 20 May 2026 11:47:24 +0200 Subject: [PATCH 2/2] docs: misc, options, pos/range --- runtime/doc/api.txt | 22 ++++---- runtime/doc/diagnostic.txt | 7 +-- runtime/doc/lua.txt | 73 +++++++++++++-------------- runtime/doc/options.txt | 15 +++--- runtime/doc/windows.txt | 5 ++ 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 ++-- src/nvim/api/win_config.c | 3 +- src/nvim/api/window.c | 8 ++- src/nvim/buffer.c | 1 + src/nvim/options.lua | 15 +++--- 17 files changed, 120 insertions(+), 133 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index a0afa7ebad..5996c3563e 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -135,10 +135,11 @@ Special types (msgpack EXT) ~ *api-indexing* Most of the API uses 0-based indices, and ranges are end-exclusive. For the -end of a range, -1 denotes the last line/column. +end of a range, -1 denotes the last line/column. See |vim.pos|, |vim.range| +for representing and converting positions. Exception: the following API functions use "mark-like" indexing (1-based -lines, 0-based columns): +lines, 0-based columns, see also |vim.pos.mark()|): - |nvim_get_mark()| - |nvim_buf_get_mark()| @@ -147,14 +148,14 @@ lines, 0-based columns): - |nvim_win_set_cursor()| Exception: the following API functions use |extmarks| indexing (0-based -indices, end-inclusive): +indices, end-inclusive, see also |vim.pos.extmark()|): - |nvim_buf_del_extmark()| - |nvim_buf_get_extmark_by_id()| - |nvim_buf_get_extmarks()| - |nvim_buf_set_extmark()| - *api-fast* *deferred* *schedule* + *api-fast* *deferred* *schedule* Most API functions are deferred: they are queued ("scheduled") on the main loop and processed sequentially with normal input. If the editor is waiting for user input in a "modal" fashion (e.g. an |input()| prompt), a deferred @@ -3948,8 +3949,7 @@ nvim_open_win({buf}, {enter}, {config}) *nvim_open_win()* option. 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. @@ -4202,12 +4202,12 @@ nvim_win_get_width({win}) *nvim_win_get_width()* (`integer`) Width as a count of columns nvim_win_hide({win}) *nvim_win_hide()* - 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. Attributes: ~ not allowed when |textlock| is active diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 03697a8639..f90cbcd842 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -442,8 +442,8 @@ Lua module: vim.diagnostic *diagnostic-api* *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. Fields: ~ • {bufnr} (`integer`) Buffer number @@ -484,7 +484,8 @@ Lua module: vim.diagnostic *diagnostic-api* enabled or disabled. If nil, enablement is ignored. See |vim.diagnostic.enable()| • {lnum}? (`integer`) Limit diagnostics to those spanning the - specified line number. + specified line number (0-indexed, see + |diagnostic-structure|). • {namespace}? (`integer[]|integer`) Limit diagnostics to one or more namespaces. • {severity}? (`vim.diagnostic.SeverityFilter`) See diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 997f2dcc21..1aebc06d4b 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -2066,8 +2066,8 @@ vim.tbl_contains({t}, {value}, {opts}) *vim.tbl_contains()* • {t} (`table`) Table to check • {value} (`any`) Value to compare or predicate function reference • {opts} (`table?`) Keyword arguments |kwargs|: - • {predicate}? (`boolean`) `value` is a function reference to - be checked (default false) + • {predicate}? (`boolean`, default: false) `value` is a + function reference to be checked Return: ~ (`boolean`) `true` if `t` contains `value` @@ -2262,22 +2262,12 @@ vim.validate({name}, {value}, {validator}, {optional}, {message}) 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): >lua + Examples: >lua vim.validate('arg1', {'foo'}, 'table') --> NOP (success) vim.validate('arg2', 'foo', 'string') @@ -2288,13 +2278,11 @@ vim.validate({name}, {value}, {validator}, {optional}, {message}) 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') < @@ -2314,8 +2302,8 @@ vim.validate({name}, {value}, {validator}, {optional}, {message}) `'userdata'`. • (`fun(val:any): boolean, string?`) A function that returns a boolean and an optional string message. - • {optional} (`boolean?`) Parameter is optional (may be omitted or - nil) + • {optional} (`boolean?`) (default: false) Parameter is optional (may + be omitted or nil) • {message} (`string?`) message when validation fails Overloads: ~ @@ -2960,14 +2948,15 @@ vim.hl.hl_op({opts}) *vim.hl.hl_op()* Parameters: ~ • {opts} (`table?`) Optional parameters - • event (default vim.v.event) Event structure. - • higroup (default "IncSearch") Highlight group for the text + • 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 + • 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 + • timeout (default: 150) Time in ms before highlight is cleared. vim.hl.priorities *vim.hl.priorities* @@ -3734,9 +3723,9 @@ vim.json.encode({obj}, {opts}) *vim.json.encode()* Lua module: vim.keymap *vim.keymap* vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()* - Remove an existing mapping. Examples: >lua + 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 }) < @@ -3751,7 +3740,8 @@ vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()* • |vim.keymap.set()| vim.keymap.set({modes}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* - 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: >lua -- Map "x" to a Lua function: @@ -3776,6 +3766,13 @@ vim.keymap.set({modes}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* 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()') < Parameters: ~ @@ -4474,10 +4471,9 @@ by |vim.Pos| objects. *vim.Pos* - 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 local pos1 = vim.pos(0, 3, 5) @@ -4507,7 +4503,7 @@ cursor({buf}, {pos}) *vim.pos.cursor()* 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) < Parameters: ~ @@ -4692,13 +4688,12 @@ Provides operations to compare, calculate, and convert ranges represented by *vim.Range* - 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 local pos1 = vim.pos(0, 3, 5) diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 87772522c2..d439b34f6d 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -1223,14 +1223,15 @@ A jump table for the options with a short description can be found at |Q_op|. 'buftype' 'bt' string (default "") local to buffer |local-noglobal| 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/doc/windows.txt b/runtime/doc/windows.txt index a7c7474ec6..aea07006e9 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -76,6 +76,11 @@ Non-focusable windows are not listed by |:tabs|, or counted by the default Windows (especially floating windows) can have many other |api-win_config| properties such as "hide" and "fixed" which also affect behavior. + *window-hidden* +If the |api-win_config| `hide` flag is set, then the window is "hidden": it +exists but is not shown anywhere. Hidden windows may be focused (the cursor +may enter it), so the cursor can perform actions in it, but the cursor will be +invisible. *window-ID* *winid* *windowid* Each window has a unique identifier called the window ID, which is permanent 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 diff --git a/src/nvim/api/win_config.c b/src/nvim/api/win_config.c index 13b70d3c26..2bc34a8da6 100644 --- a/src/nvim/api/win_config.c +++ b/src/nvim/api/win_config.c @@ -145,8 +145,7 @@ /// 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. diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c index 5c95c15745..bdca9111bf 100644 --- a/src/nvim/api/window.c +++ b/src/nvim/api/window.c @@ -343,12 +343,10 @@ Boolean nvim_win_is_valid(Window win) return ret; } -/// 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 |window-ID|, or 0 for current window /// @param[out] err Error details, if any diff --git a/src/nvim/buffer.c b/src/nvim/buffer.c index fa4304f765..73dcac5f4e 100644 --- a/src/nvim/buffer.c +++ b/src/nvim/buffer.c @@ -1476,6 +1476,7 @@ static int do_buffer_ext(int action, int start, int dir, int count, int flags) const int rv = switch_win_noblock(&switchwin, firstwin, curtab, true); assert(rv == OK); (void)rv; + // retry (recurse) do_buffer_ext(action, start, dir, count, flags); restore_win_noblock(&switchwin, true); } diff --git a/src/nvim/options.lua b/src/nvim/options.lua index 7a74739ce0..076e6a6d4d 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -944,14 +944,15 @@ local options = { }, desc = [=[ 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