Merge #32810 docs

1 files changed, 32 insertions, 28 deletions

diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index a44ad6c7d9..9df5a0b5f2 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -160,45 +160,43 @@ vim.v.errors = ...
 ---                    an aborting condition (e.g. `c_Esc` or
 ---                    `c_CTRL-C` for `CmdlineLeave`).
 ---   chan             `channel-id`
----   info             Dict of arbitrary event data.
+---   changed_window   Is `v:true` if the event fired while
+---                    changing window  (or tab) on `DirChanged`.
 ---   cmdlevel         Level of cmdline.
 ---   cmdtype          Type of cmdline, `cmdline-char`.
+---   col              Column count of popup menu on `CompleteChanged`,
+---                    relative to screen.
+---   complete_type    See `complete_info_mode`
+---   complete_word    The selected word, or empty if completion
+---                    was abandoned/discarded.
+---   completed_item   Current selected item on `CompleteChanged`,
+---                    or `{}` if no item selected.
 ---   cwd              Current working directory.
+---   height           Height of popup menu on `CompleteChanged`
 ---   inclusive        Motion is `inclusive`, else exclusive.
----   scope            Event-specific scope name.
+---   info             Dict of arbitrary event data.
 ---   operator         Current `operator`.  Also set for Ex
 ---                    commands (unlike `v:operator`). For
 ---                    example if `TextYankPost` is triggered
 ---                    by the `:yank` Ex command then
 ---                    `v:event.operator` is "y".
+---   reason           `CompleteDone` reason.
 ---   regcontents      Text stored in the register as a
 ---                    `readfile()`-style list of lines.
----   regname          Requested register (e.g "x" for "xyy)
----                    or the empty string for an unnamed
----                    operation.
+---   regname          Requested register (e.g "x" for "xyy), or
+---                    empty string for an unnamed operation.
 ---   regtype          Type of register as returned by
 ---                    `getregtype()`.
----   visual           Selection is visual (as opposed to,
----                    e.g., via motion).
----   completed_item   Current selected complete item on
----                    `CompleteChanged`, Is `{}` when no complete
----                    item selected.
----   height           Height of popup menu on `CompleteChanged`
----   width            Width of popup menu on `CompleteChanged`
 ---   row              Row count of popup menu on `CompleteChanged`,
 ---                    relative to screen.
----   col              Col count of popup menu on `CompleteChanged`,
----                    relative to screen.
+---   scope            Event-specific scope name.
+---   scrollbar        `v:true` if popup menu has a scrollbar, or
+---                    `v:false` if not.
 ---   size             Total number of completion items on
 ---                    `CompleteChanged`.
----   scrollbar        Is `v:true` if popup menu have scrollbar, or
----                    `v:false` if not.
----   changed_window   Is `v:true` if the event fired while
----                    changing window  (or tab) on `DirChanged`.
 ---   status           Job status or exit code, -1 means "unknown". `TermClose`
----   reason           Reason for completion being done. `CompleteDone`
----   complete_word    The word that was selected, empty if abandoned complete.
----   complete_type    See `complete_info_mode`
+---   visual           Selection is visual (as opposed to e.g. a motion range).
+---   width            Width of popup menu on `CompleteChanged`
 ---   windows          List of window IDs that changed on `WinResized`
 --- @type vim.v.event
 vim.v.event = ...
@@ -590,15 +588,21 @@ vim.v.searchforward = ...
 ---                                                      *$NVIM*
 --- $NVIM is set by `terminal` and `jobstart()`, and is thus
 --- a hint that the current environment is a subprocess of Nvim.
---- Example:
 ---
---- ```vim
----   if $NVIM
----     echo nvim_get_chan_info(v:parent)
----   endif
---- ```
+--- Example: a child Nvim process can detect and make requests to
+--- its parent Nvim:
+---
+--- ```lua
 ---
---- Note the contents of $NVIM may change in the future.
+---   if vim.env.NVIM then
+---     local ok, chan = pcall(vim.fn.sockconnect, 'pipe', vim.env.NVIM, {rpc=true})
+---     if ok and chan then
+---       local client = vim.api.nvim_get_chan_info(chan).client
+---       local rv = vim.rpcrequest(chan, 'nvim_exec_lua', [[return ... + 1]], { 41 })
+---       vim.print(('got "%s" from parent Nvim'):format(rv))
+---     end
+---   end
+--- ```
 --- @type string
 vim.v.servername = ...