docs: misc #35459

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
+    Sends raw data to channel `chan`. |channel-bytes|
-    process. For the stdio channel |channel-stdio|, it writes to Nvim's
+    • For a job, it writes it to the stdin of the process.
-    stdout. For an internal terminal instance (|nvim_open_term()|) it writes
+    • For the stdio channel |channel-stdio|, it writes to Nvim's stdout.
-    directly to terminal output. See |channel-bytes| for more information.
+    • 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
+    This function writes raw data, not RPC messages. Use |vim.rpcrequest()|
-    created with `rpc=true` then the channel expects RPC messages, use
+    and |vim.rpcnotify()| if the channel expects RPC messages (i.e. it was
-    |vim.rpcnotify()| and |vim.rpcrequest()| instead.
+    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
+      • {chan}  (`integer`) Channel id
-      • {data}  (`string`) data to write. 8-bit clean: can contain NUL bytes.
+      • {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"
+    Emits a "ui_send" event to all UIs with the "stdout_tty" |ui-option| set.
-    |ui-option| set. UIs are expected to write the received data to a
+    UIs are expected to write the received data to a connected TTY if one
-    connected TTY if one exists.
+    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:
+    Supports these events:
-    • "termresponse": The terminal sent a DA1, OSC, DCS, or APC response
+    • "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|.
 

runtime/doc/gui.txt

@@ -71,21 +71,27 @@ Restart Nvim
 
                                                 *:restart*
 :restart [+cmd] [command]
-                Restarts the Nvim server with the same startup arguments
+                Restarts Nvim.
-                |v:argv| and reattaches the current UI to the new server.
+
-                All other UIs will detach.
+                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: stop with `:qall!`, then restart: >
-                Example: `:restart +qall! lua vim.pack.update()` stops the
+                    :restart +qall!
-                server using `:qall!` and starts the new server with the
+<                Example: restart and restore the current session: >
-                argument `-c lua vim.pack.update()`. See also |-c|.
+                    :mksession! Session.vim | restart source Session.vim
-
+<                Example: restart and update plugins: >
-                Note: |+cmd| defaults to `qall!` if not specified.
+                    :restart +qall! lua vim.pack.update()
-                Note: If the current UI hasn't implemented the "restart" UI
+<
-                event, this command is equivalent to `:qall`.
                 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

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
+EXPERIMENTAL: This API may change in the future. Its semantics are not yet
-finalized, and the stability of this API is not guaranteed. Avoid using it
+finalized. Subscribe to https://github.com/neovim/neovim/issues/25509 to stay
-outside of Nvim. You may subscribe to or participate in the tracking issue
+updated or contribute to its development.
-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
+Provides operations to compare, calculate, and convert positions represented
-comparisons and conversions between various types of positions.
+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
+EXPERIMENTAL: This API may change in the future. Its semantics are not yet
-finalized, and the stability of this API is not guaranteed. Avoid using it
+finalized. Subscribe to https://github.com/neovim/neovim/issues/25509 to stay
-outside of Nvim. You may subscribe to or participate in the tracking issue
+updated or contribute to its development.
-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
+Provides operations to compare, calculate, and convert ranges represented by
-comparisons as well as containment checks (for positions and for other
+|vim.Range| objects.
-ranges). conversions between various types of ranges is also provided.
 
 
 *vim.Range*

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
+--- Sends raw data to channel `chan`. `channel-bytes`
---- stdin of the process. For the stdio channel `channel-stdio`,
+--- - For a job, it writes it to the stdin of the process.
---- it writes to Nvim's stdout.  For an internal terminal instance
+--- - For the stdio channel `channel-stdio`, it writes to Nvim's stdout.
---- (`nvim_open_term()`) it writes directly to terminal output.
+--- - 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
+--- This function writes raw data, not RPC messages. Use `vim.rpcrequest()` and `vim.rpcnotify()` if
---- was created with `rpc=true` then the channel expects RPC
+--- the channel expects RPC messages (i.e. it was created with `rpc=true`).
---- messages, use `vim.rpcnotify()` and `vim.rpcrequest()` instead.
 ---
---- @param chan integer id of the channel
+--- To write data to the `TUI` host terminal, see `nvim_ui_send()`.
---- @param data string data to write. 8-bit clean: can contain NUL bytes.
+---
+--- @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
+--- Emits a "ui_send" event to all UIs with the "stdout_tty" `ui-option` set. UIs are expected to
---- expected to write the received data to a connected TTY if one exists.
+--- 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

runtime/lua/vim/pos.lua

@@ -1,15 +1,11 @@
 ---@brief
 ---
---- WARNING: This module is under experimental support.
+--- EXPERIMENTAL: This API may change in the future. Its semantics are not yet finalized.
---- Its semantics are not yet finalized,
+--- Subscribe to https://github.com/neovim/neovim/issues/25509
---- 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.
 ---
---- Built on |vim.Pos| objects, this module offers operations
+--- Provides operations to compare, calculate, and convert positions represented by |vim.Pos|
---- that support comparisons and conversions between various types of positions.
+--- objects.
 
 local api = vim.api
 local validate = vim.validate

runtime/lua/vim/range.lua

@@ -1,17 +1,11 @@
 ---@brief
 ---
---- WARNING: This module is under experimental support.
+--- EXPERIMENTAL: This API may change in the future. Its semantics are not yet finalized.
---- Its semantics are not yet finalized,
+--- Subscribe to https://github.com/neovim/neovim/issues/25509
---- 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.
 ---
---- Built on |vim.Range| objects, this module offers operations
+--- Provides operations to compare, calculate, and convert ranges represented by |vim.Range|
---- that support comparisons as well as containment checks
+--- objects.
---- (for positions and for other ranges).
---- conversions between various types of ranges is also provided.
 
 local validate = vim.validate
 

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
+///   - "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response sequence to Nvim.
-///                     Nvim. The payload is the received response. Sets
+///                     The payload is the received response. Sets |v:termresponse| and fires
-///                     |v:termresponse| and fires |TermResponse|.
+///                     |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
+/// Emits a "ui_send" event to all UIs with the "stdout_tty" |ui-option| set. UIs are expected to
-/// expected to write the received data to a connected TTY if one exists.
+/// write the received data to a connected TTY if one exists.
 ///
 /// @param channel_id
 /// @param content Content to write to the TTY

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
+/// Sends raw data to channel `chan`. |channel-bytes|
-/// stdin of the process. For the stdio channel |channel-stdio|,
+/// - For a job, it writes it to the stdin of the process.
-/// it writes to Nvim's stdout.  For an internal terminal instance
+/// - For the stdio channel |channel-stdio|, it writes to Nvim's stdout.
-/// (|nvim_open_term()|) it writes directly to terminal output.
+/// - 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
+/// This function writes raw data, not RPC messages. Use |vim.rpcrequest()| and |vim.rpcnotify()| if
-/// was created with `rpc=true` then the channel expects RPC
+/// the channel expects RPC messages (i.e. it was created with `rpc=true`).
-/// messages, use |vim.rpcnotify()| and |vim.rpcrequest()| instead.
 ///
-/// @param chan id of the channel
+/// To write data to the |TUI| host terminal, see |nvim_ui_send()|.
-/// @param data data to write. 8-bit clean: can contain NUL bytes.
+///
+/// @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

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)

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)

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)