docs: misc

runtime/lua/vim/_meta/api.lua

@@ -485,10 +485,7 @@ function vim.api.nvim_buf_get_offset(buffer, index) end
 --- @return any
 function vim.api.nvim_buf_get_option(buffer, name) end
 
---- Gets a range from the buffer.
----
---- This differs from `nvim_buf_get_lines()` in that it allows retrieving only
---- portions of a line.
+--- Gets a range from the buffer (may be partial lines, unlike `nvim_buf_get_lines()`).
 ---
 --- Indexing is zero-based. Row indices are end-inclusive, and column indices
 --- are end-exclusive.
@@ -698,7 +695,7 @@ function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end
 ---
 --- Indexing is zero-based, end-exclusive. Negative indices are interpreted
 --- as length+1+index: -1 refers to the index past the end. So to change
---- or delete the last element use start=-2 and end=-1.
+--- or delete the last line use start=-2 and end=-1.
 ---
 --- To insert lines at a given index, set `start` and `end` to the same index.
 --- To delete a range of lines, set `replacement` to an empty array.
@@ -2089,7 +2086,7 @@ function vim.api.nvim_set_current_line(line) end
 --- @param tabpage integer `tab-ID` to focus
 function vim.api.nvim_set_current_tabpage(tabpage) end
 
---- Sets the current window. Also changes tabpage, if necessary.
+--- Sets the current window (and tabpage, implicitly).
 ---
 --- @param window integer `window-ID` to focus
 function vim.api.nvim_set_current_win(window) end

runtime/lua/vim/_meta/options.lua

@@ -2010,9 +2010,10 @@ vim.o.et = vim.o.expandtab
 vim.bo.expandtab = vim.o.expandtab
 vim.bo.et = vim.bo.expandtab
 
---- Automatically execute .nvim.lua, .nvimrc, and .exrc files in the
---- current directory, if the file is in the `trust` list. Use `:trust` to
---- manage trusted files. See also `vim.secure.read()`.
+--- Enables project-local configuration. Nvim will execute any .nvim.lua,
+--- .nvimrc, or .exrc file found in the `current-directory`, if the file is
+--- in the `trust` list. Use `:trust` to manage trusted files. See also
+--- `vim.secure.read()`.
 ---
 --- Compare 'exrc' to `editorconfig`:
 --- - 'exrc' can execute any code; editorconfig only specifies settings.

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
+---
+---   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
 --- ```
----
---- Note the contents of $NVIM may change in the future.
 --- @type string
 vim.v.servername = ...
 

runtime/lua/vim/lsp/completion.lua

@@ -6,6 +6,8 @@
 ---
 --- Example: activate LSP-driven auto-completion:
 --- ```lua
+--- -- Works best with completeopt=noselect.
+--- vim.cmd[[set completeopt+=menuone,noselect,popup]]
 --- vim.lsp.start({
 ---   name = 'ts_ls',
 ---   cmd = …,