commit bccec33f5a011fac7f0a90260c72c2ac2f4c334f
parent b2a136bd67ab1fe48e71e884c08de43230892667
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sun, 24 Aug 2025 19:43:48 -0400
docs: misc #35459
Diffstat:
11 files changed, 98 insertions(+), 100 deletions(-)
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
@@ -557,14 +557,17 @@ created for extmark changes.
Global Functions *api-global*
nvim_chan_send({chan}, {data}) *nvim_chan_send()*
- Send data to channel `id`. For a job, it writes it to the stdin of the
- process. For the stdio channel |channel-stdio|, it writes to Nvim's
- stdout. For an internal terminal instance (|nvim_open_term()|) it writes
- directly to terminal output. See |channel-bytes| for more information.
+ Sends raw data to channel `chan`. |channel-bytes|
+ • For a job, it writes it to the stdin of the process.
+ • For the stdio channel |channel-stdio|, it writes to Nvim's stdout.
+ • For an internal terminal instance (|nvim_open_term()|) it writes
+ directly to terminal output.
- This function writes raw data, not RPC messages. If the channel was
- created with `rpc=true` then the channel expects RPC messages, use
- |vim.rpcnotify()| and |vim.rpcrequest()| instead.
+ This function writes raw data, not RPC messages. Use |vim.rpcrequest()|
+ and |vim.rpcnotify()| if the channel expects RPC messages (i.e. it was
+ created with `rpc=true`).
+
+ To write data to the |TUI| host terminal, see |nvim_ui_send()|.
Attributes: ~
|RPC| only
@@ -572,8 +575,8 @@ nvim_chan_send({chan}, {data}) *nvim_chan_send()*
Since: 0.5.0
Parameters: ~
- • {chan} (`integer`) id of the channel
- • {data} (`string`) data to write. 8-bit clean: can contain NUL bytes.
+ • {chan} (`integer`) Channel id
+ • {data} (`string`) Data to write. 8-bit clean: may contain NUL bytes.
nvim_create_buf({listed}, {scratch}) *nvim_create_buf()*
Creates a new, empty, unnamed buffer.
@@ -3601,11 +3604,13 @@ nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()*
nvim_ui_send({content}) *nvim_ui_send()*
WARNING: This feature is experimental/unstable.
- Sends arbitrary data to a UI.
+ Sends arbitrary data to a UI. Use this instead of |nvim_chan_send()| or
+ `io.stdout:write()`, if you really want to write to the |TUI| host
+ terminal.
- This sends a "ui_send" event to any UI that has the "stdout_tty"
- |ui-option| set. UIs are expected to write the received data to a
- connected TTY if one exists.
+ Emits a "ui_send" event to all UIs with the "stdout_tty" |ui-option| set.
+ UIs are expected to write the received data to a connected TTY if one
+ exists.
Parameters: ~
• {content} (`string`) Content to write to the TTY
@@ -3631,10 +3636,10 @@ nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()*
• {value} (`any`)
nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()*
- Tells Nvim when a terminal event has occurred
+ Tells Nvim when a host-terminal event occurred.
- The following terminal events are supported:
- • "termresponse": The terminal sent a DA1, OSC, DCS, or APC response
+ Supports these events:
+ • "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response
sequence to Nvim. The payload is the received response. Sets
|v:termresponse| and fires |TermResponse|.
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
@@ -71,21 +71,27 @@ Restart Nvim
*:restart*
:restart [+cmd] [command]
- Restarts the Nvim server with the same startup arguments
- |v:argv| and reattaches the current UI to the new server.
- All other UIs will detach.
+ Restarts Nvim.
- Use with `:confirm` to prompt if changes have been made.
+ 1. Stops Nvim using `:qall!` (or |+cmd|, if given).
+ 2. Starts a new Nvim server using the same |v:argv|,
+ optionally running [command] at startup. |-c|
+ 3. Attaches the current UI to the new Nvim server. Other UIs
+ (if any) will not reattach on restart (this may change in
+ the future).
- Example: `:restart +qall!` stops the server using `:qall!`.
- Example: `:restart +qall! lua vim.pack.update()` stops the
- server using `:qall!` and starts the new server with the
- argument `-c lua vim.pack.update()`. See also |-c|.
+ Use with `:confirm` to prompt if changes have been made.
- Note: |+cmd| defaults to `qall!` if not specified.
- Note: If the current UI hasn't implemented the "restart" UI
- event, this command is equivalent to `:qall`.
+ Example: stop with `:qall!`, then restart: >
+ :restart +qall!
+< Example: restart and restore the current session: >
+ :mksession! Session.vim | restart source Session.vim
+< Example: restart and update plugins: >
+ :restart +qall! lua vim.pack.update()
+<
Note: Only works if the UI and server are on the same system.
+ Note: If the UI hasn't implemented the "restart" UI event,
+ this command is equivalent to `:qall!`.
------------------------------------------------------------------------------
Connect UI to a different server
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -3952,14 +3952,12 @@ vim.net.request({url}, {opts}, {on_response}) *vim.net.request()*
==============================================================================
Lua module: vim.pos *vim.pos*
-WARNING: This module is under experimental support. Its semantics are not yet
-finalized, and the stability of this API is not guaranteed. Avoid using it
-outside of Nvim. You may subscribe to or participate in the tracking issue
-https://github.com/neovim/neovim/issues/25509 to stay updated or contribute to
-its development.
+EXPERIMENTAL: This API may change in the future. Its semantics are not yet
+finalized. Subscribe to https://github.com/neovim/neovim/issues/25509 to stay
+updated or contribute to its development.
-Built on |vim.Pos| objects, this module offers operations that support
-comparisons and conversions between various types of positions.
+Provides operations to compare, calculate, and convert positions represented
+by |vim.Pos| objects.
*vim.Pos*
@@ -4038,15 +4036,12 @@ Pos:to_lsp({pos}, {position_encoding}) *Pos:to_lsp()*
==============================================================================
Lua module: vim.range *vim.range*
-WARNING: This module is under experimental support. Its semantics are not yet
-finalized, and the stability of this API is not guaranteed. Avoid using it
-outside of Nvim. You may subscribe to or participate in the tracking issue
-https://github.com/neovim/neovim/issues/25509 to stay updated or contribute to
-its development.
+EXPERIMENTAL: This API may change in the future. Its semantics are not yet
+finalized. Subscribe to https://github.com/neovim/neovim/issues/25509 to stay
+updated or contribute to its development.
-Built on |vim.Range| objects, this module offers operations that support
-comparisons as well as containment checks (for positions and for other
-ranges). conversions between various types of ranges is also provided.
+Provides operations to compare, calculate, and convert ranges represented by
+|vim.Range| objects.
*vim.Range*
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
@@ -813,18 +813,18 @@ function vim.api.nvim_call_dict_function(dict, fn, args) end
--- @return any # Result of the function call
function vim.api.nvim_call_function(fn, args) end
---- Send data to channel `id`. For a job, it writes it to the
---- stdin of the process. For the stdio channel `channel-stdio`,
---- it writes to Nvim's stdout. For an internal terminal instance
---- (`nvim_open_term()`) it writes directly to terminal output.
---- See `channel-bytes` for more information.
----
---- This function writes raw data, not RPC messages. If the channel
---- was created with `rpc=true` then the channel expects RPC
---- messages, use `vim.rpcnotify()` and `vim.rpcrequest()` instead.
----
---- @param chan integer id of the channel
---- @param data string data to write. 8-bit clean: can contain NUL bytes.
+--- Sends raw data to channel `chan`. `channel-bytes`
+--- - For a job, it writes it to the stdin of the process.
+--- - For the stdio channel `channel-stdio`, it writes to Nvim's stdout.
+--- - For an internal terminal instance (`nvim_open_term()`) it writes directly to terminal output.
+---
+--- This function writes raw data, not RPC messages. Use `vim.rpcrequest()` and `vim.rpcnotify()` if
+--- the channel expects RPC messages (i.e. it was created with `rpc=true`).
+---
+--- To write data to the `TUI` host terminal, see `nvim_ui_send()`.
+---
+--- @param chan integer Channel id
+--- @param data string Data to write. 8-bit clean: may contain NUL bytes.
function vim.api.nvim_chan_send(chan, data) end
--- Clears all autocommands selected by {opts}. To delete autocmds see `nvim_del_autocmd()`.
@@ -2340,10 +2340,11 @@ function vim.api.nvim_tabpage_set_var(tabpage, name, value) end
--- @param win integer `window-ID`, must already belong to {tabpage}
function vim.api.nvim_tabpage_set_win(tabpage, win) end
---- Sends arbitrary data to a UI.
+--- Sends arbitrary data to a UI. Use this instead of `nvim_chan_send()` or `io.stdout:write()`, if
+--- you really want to write to the `TUI` host terminal.
---
---- This sends a "ui_send" event to any UI that has the "stdout_tty" `ui-option` set. UIs are
---- expected to write the received data to a connected TTY if one exists.
+--- Emits a "ui_send" event to all UIs with the "stdout_tty" `ui-option` set. UIs are expected to
+--- write the received data to a connected TTY if one exists.
---
--- @param content string Content to write to the TTY
function vim.api.nvim_ui_send(content) end
diff --git a/runtime/lua/vim/pos.lua b/runtime/lua/vim/pos.lua
@@ -1,15 +1,11 @@
---@brief
---
---- WARNING: This module is under experimental support.
---- Its semantics are not yet finalized,
---- and the stability of this API is not guaranteed.
---- Avoid using it outside of Nvim.
---- You may subscribe to or participate in the tracking issue
---- https://github.com/neovim/neovim/issues/25509
+--- EXPERIMENTAL: This API may change in the future. Its semantics are not yet finalized.
+--- Subscribe to https://github.com/neovim/neovim/issues/25509
--- to stay updated or contribute to its development.
---
---- Built on |vim.Pos| objects, this module offers operations
---- that support comparisons and conversions between various types of positions.
+--- Provides operations to compare, calculate, and convert positions represented by |vim.Pos|
+--- objects.
local api = vim.api
local validate = vim.validate
diff --git a/runtime/lua/vim/range.lua b/runtime/lua/vim/range.lua
@@ -1,17 +1,11 @@
---@brief
---
---- WARNING: This module is under experimental support.
---- Its semantics are not yet finalized,
---- and the stability of this API is not guaranteed.
---- Avoid using it outside of Nvim.
---- You may subscribe to or participate in the tracking issue
---- https://github.com/neovim/neovim/issues/25509
+--- EXPERIMENTAL: This API may change in the future. Its semantics are not yet finalized.
+--- Subscribe to https://github.com/neovim/neovim/issues/25509
--- to stay updated or contribute to its development.
---
---- Built on |vim.Range| objects, this module offers operations
---- that support comparisons as well as containment checks
---- (for positions and for other ranges).
---- conversions between various types of ranges is also provided.
+--- Provides operations to compare, calculate, and convert ranges represented by |vim.Range|
+--- objects.
local validate = vim.validate
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
@@ -567,13 +567,13 @@ void nvim_ui_pum_set_bounds(uint64_t channel_id, Float width, Float height, Floa
ui->pum_pos = true;
}
-/// Tells Nvim when a terminal event has occurred
+/// Tells Nvim when a host-terminal event occurred.
///
-/// The following terminal events are supported:
+/// Supports these events:
///
-/// - "termresponse": The terminal sent a DA1, OSC, DCS, or APC response sequence to
-/// Nvim. The payload is the received response. Sets
-/// |v:termresponse| and fires |TermResponse|.
+/// - "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response sequence to Nvim.
+/// The payload is the received response. Sets |v:termresponse| and fires
+/// |TermResponse|.
///
/// @param channel_id
/// @param event Event name
@@ -1115,10 +1115,11 @@ free_ret:
arena_mem_free(arena_finish(&arena));
}
-/// Sends arbitrary data to a UI.
+/// Sends arbitrary data to a UI. Use this instead of |nvim_chan_send()| or `io.stdout:write()`, if
+/// you really want to write to the |TUI| host terminal.
///
-/// This sends a "ui_send" event to any UI that has the "stdout_tty" |ui-option| set. UIs are
-/// expected to write the received data to a connected TTY if one exists.
+/// Emits a "ui_send" event to all UIs with the "stdout_tty" |ui-option| set. UIs are expected to
+/// write the received data to a connected TTY if one exists.
///
/// @param channel_id
/// @param content Content to write to the TTY
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
@@ -1096,18 +1096,18 @@ static void term_close(void *data)
channel_decref(chan);
}
-/// Send data to channel `id`. For a job, it writes it to the
-/// stdin of the process. For the stdio channel |channel-stdio|,
-/// it writes to Nvim's stdout. For an internal terminal instance
-/// (|nvim_open_term()|) it writes directly to terminal output.
-/// See |channel-bytes| for more information.
-///
-/// This function writes raw data, not RPC messages. If the channel
-/// was created with `rpc=true` then the channel expects RPC
-/// messages, use |vim.rpcnotify()| and |vim.rpcrequest()| instead.
-///
-/// @param chan id of the channel
-/// @param data data to write. 8-bit clean: can contain NUL bytes.
+/// Sends raw data to channel `chan`. |channel-bytes|
+/// - For a job, it writes it to the stdin of the process.
+/// - For the stdio channel |channel-stdio|, it writes to Nvim's stdout.
+/// - For an internal terminal instance (|nvim_open_term()|) it writes directly to terminal output.
+///
+/// This function writes raw data, not RPC messages. Use |vim.rpcrequest()| and |vim.rpcnotify()| if
+/// the channel expects RPC messages (i.e. it was created with `rpc=true`).
+///
+/// To write data to the |TUI| host terminal, see |nvim_ui_send()|.
+///
+/// @param chan Channel id
+/// @param data Data to write. 8-bit clean: may contain NUL bytes.
/// @param[out] err Error details, if any
void nvim_chan_send(Integer chan, String data, Error *err)
FUNC_API_SINCE(7) FUNC_API_REMOTE_ONLY FUNC_API_LUA_ONLY
diff --git a/test/functional/lua/buffer_updates_spec.lua b/test/functional/lua/buffer_updates_spec.lua
@@ -60,7 +60,7 @@ before_each(function()
end)
end)
-describe('lua buffer event callbacks: on_lines', function()
+describe('lua: nvim_buf_attach on_lines', function()
local function setup_eventcheck(verify, utf_sizes, lines)
local lastsize
api.nvim_buf_set_lines(0, 0, -1, true, lines)
diff --git a/test/functional/lua/pos_spec.lua b/test/functional/lua/pos_spec.lua
@@ -30,7 +30,7 @@ describe('vim.pos', function()
eq(buf, pos.buf)
end)
- it('supports comparisons by overloaded mathmatical operators', function()
+ it('comparisons by overloaded operators', function()
eq(
true,
exec_lua(function()
@@ -69,7 +69,7 @@ describe('vim.pos', function()
)
end)
- it('supports conversion between vim.Pos and lsp.Position', function()
+ it('converts between vim.Pos and lsp.Position', function()
local buf = exec_lua(function()
return vim.api.nvim_get_current_buf()
end)
diff --git a/test/functional/lua/range_spec.lua b/test/functional/lua/range_spec.lua
@@ -31,7 +31,7 @@ describe('vim.range', function()
eq(buf, range.end_.buf)
end)
- it('create a range from two positions when optional fields are not matched', function()
+ it('creates a range from two positions when optional fields are not matched', function()
local range = exec_lua(function()
return vim.range(vim.pos(3, 5), vim.pos(4, 6))
end)
@@ -62,7 +62,7 @@ describe('vim.range', function()
eq(success, false)
end)
- it('supports conversion between vim.Range and lsp.Range', function()
+ it('converts between vim.Range and lsp.Range', function()
local buf = exec_lua(function()
return vim.api.nvim_get_current_buf()
end)
