docs: misc neovim#35459

Author: justinmk

runtime/doc/api.txt

@@ -557,23 +557,26 @@ 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
         Lua |vim.api| only
         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|.
 

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

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*

runtime/lua/vim/_meta/api.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

runtime/lua/vim/pos.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
 

runtime/lua/vim/range.lua

@@ -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 @@ void remote_ui_event(RemoteUI *ui, char *name, Array args)
   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

src/nvim/api/ui.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

src/nvim/api/vim.c

@@ -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/buffer_updates_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)