docs: misc #35459

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

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

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