diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 1a041cf5ad..30c7f3c2c0 100644 --- 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 index aab9861fa0..de61558bc0 100644 --- 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. + + 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). Use with `:confirm` to prompt if changes have been made. - 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|. - - 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 index b30b7d0174..8743681322 100644 --- 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 index 43a3fd73a7..624b611bda 100644 --- 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. +--- 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`). --- ---- @param chan integer id of the channel ---- @param data string data to write. 8-bit clean: can contain NUL bytes. +--- 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 index 648be60e81..deca94d9c1 100644 --- 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 index 7fdb170874..d8fa52ef80 100644 --- 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 index 16c478e215..654da61187 100644 --- 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 index d2c436dc4d..5f5a93ec54 100644 --- 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. +/// 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`). /// -/// @param chan id of the channel -/// @param data data to write. 8-bit clean: can contain NUL bytes. +/// 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 index a8c7ba16b0..443b1ccc19 100644 --- 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 index 176c6489b0..c9d33b449c 100644 --- 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 index 662cc3a5e6..b211b2dc97 100644 --- 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)