refactor: cleanup, docs #40480

runtime/lua/vim/_core/server.lua

@@ -1,6 +1,4 @@
-local fs = vim.fs
-local uv = vim.uv
--- For "--listen" and related functionality.
+-- For "--listen", ":restart", and related remote/server functionality.
 
 local M = {}
 
@@ -156,34 +154,32 @@ function M.rebind_after_restart(canonical_addr, expected_uis)
   end)
 end
 
--- Called by ex_restart(). Saves the current session and calls back to
--- ex_restart() with the necessary arguments to restore the session.
+-- Called by ex_restart(). Saves the current session and calls ex_restart() (again) with the
+-- updated arguments.
+--
 -- TODO: https://github.com/neovim/neovim/issues/34204
+--
 --- @param eap vim._core.ExCmdArgs
 --- @param extra { quit_cmd: string }
 function M.ex_session_restart(eap, extra)
-  -- Commands to run after restart
-  local after_cmd = eap.args
+  local after_cmd = eap.args -- User-provided [command].
   assert(not after_cmd:find(']==]'))
 
-  -- Use custom quit command if provided
-  local quit_cmd = 'qall'
-  if extra.quit_cmd ~= '' then
-    quit_cmd = extra.quit_cmd
-  end
+  -- Use custom +cmd if given.
+  local quit_cmd = extra.quit_cmd == '' and 'qall' or extra.quit_cmd
 
-  -- Preserve the value of v:this_session
+  -- Preserve v:this_session in the restarted Nvim.
   local this_session = vim.v.this_session
   assert(not this_session:find(']==]'))
 
-  -- Get temp file to write session to
-  local temp_dir = fs.abspath(fs.dirname(fs.dirname(vim.fn.tempname())))
-  assert(not temp_dir:find(']==]'))
-  local fd, session = uv.fs_mkstemp(fs.joinpath(temp_dir, 'restart_session_XXXXXX'))
+  -- Nvim temp "root dir": "/tmp/…/nvim.<user>/"
+  local tmproot = vim.fs.abspath(vim.fs.dirname(vim.fs.dirname(vim.fn.tempname())))
+  assert(not tmproot:find(']==]'))
+  local fd, session = vim.uv.fs_mkstemp(vim.fs.joinpath(tmproot, 'restart_session_XXXXXX'))
   if not fd then
     error('Failed to get temporary filename for restart session')
   end
-  uv.fs_close(fd)
+  vim.uv.fs_close(fd)
 
   -- Write session
   local session_arg = vim.fn.fnameescape(session)
@@ -195,22 +191,20 @@ function M.ex_session_restart(eap, extra)
   table.insert(after_list, ('vim.cmd("source %s")'):format(session_arg))
   table.insert(after_list, ('pcall(vim.fs.rm, [==[%s]==])'):format(session))
   table.insert(after_list, ('vim.v.this_session = [==[%s]==]'):format(this_session))
-  -- User provided command
   if after_cmd ~= '' then
     table.insert(after_list, ('vim.cmd([==[%s]==])'):format(after_cmd))
   end
-  -- Concatenate everything together
   local after = 'lua ' .. table.concat(after_list, ';')
 
   -- Restart Neovim and run our Lua commands
   local success, msg = pcall(function()
-    -- "+:::" special argument tells the C handler that this is actually a non-bang restart
-    -- That way, v:startreason can be set correctly
+    -- "+:::" dummy prefix tells the C handler that this is actually a non-bang restart.
+    -- Then v:startreason (if any) can be preserved.
     vim.cmd.restart { '+:::', quit_cmd, after, bang = true }
   end)
 
   if not success then
-    fs.rm(session, { force = true })
+    vim.fs.rm(session, { force = true })
     error(msg)
   end
 end

runtime/lua/vim/_meta/api.gen.lua

@@ -509,7 +509,7 @@ function vim.api.nvim_buf_get_lines(buf, start, end_, strict_indexing) end
 --- uppercase/file mark set in another buffer.
 function vim.api.nvim_buf_get_mark(buf, name) end
 
---- Gets the full file name for the buffer
+--- Gets the full/absolute filepath of the buffer, or the buffer name for non-file buffers.
 ---
 --- @param buf integer Buffer id, or 0 for current buffer
 --- @return string # Buffer name

runtime/lua/vim/_meta/options.gen.lua

@@ -169,11 +169,13 @@ vim.bo.autoindent = vim.o.autoindent
 vim.bo.ai = vim.bo.autoindent
 
 --- When a file was changed outside of Nvim, automatically read it again.
---- Skipped if the file was deleted, so you have the text from before it
---- was deleted. If the file appears again then it is read. `timestamp`
+--- Skipped if the file was deleted (so you still have the last-available
+--- text). If the file appears again, then it is read; you can `undo` to
+--- see the previous contents. `timestamp`
 ---
---- This is partially driven by OS filewatcher events `uv_fs_event_t`, so
---- even the current buffer may be updated.
+--- This is driven (partially) by OS filewatcher events `uv_fs_event_t`,
+--- so buffers are updated immediately (instead of only on focus-change or
+--- shell-commands).
 ---
 --- If this option has a local value, use this command to switch back to
 --- using the global value:
@@ -228,13 +230,13 @@ vim.go.awa = vim.go.autowriteall
 --- that background type.  The `TUI` or other UI sets this on startup
 --- if it can detect the background color, and re-detects it whenever a UI
 --- attaches later, unless 'background' was set explicitly.  When multiple
---- terminal UIs are attached they share one value, taken from whichever
---- terminal reports its background last (which may not be the most
---- recently attached one, since it depends on response speed).
+--- UIs are attached they share one value, decided by "last wins" (may
+--- not be the most recently-attached UI, since it depends on response
+--- speed).
 ---
 --- This option does NOT change the background color, it tells Nvim what
---- the "inherited" (terminal/GUI) background looks like.
---- See `:hi-normal` if you want to set the background color explicitly.
+--- the "inherited" (terminal/GUI) background looks like. See `:hi-normal`
+--- to set the background color explicitly.
 --- 					*g:colors_name*
 --- When a color scheme is loaded (the "g:colors_name" variable is set)
 --- changing 'background' will cause the color scheme to be reloaded.  If
@@ -242,17 +244,16 @@ vim.go.awa = vim.go.autowriteall
 --- However, if the color scheme sets 'background' itself the effect may
 --- be undone.  First delete the "g:colors_name" variable when needed.
 ---
---- Normally this option would be set in the vimrc file.  Possibly
---- depending on the terminal name.  Example:
+--- Historically, this option was set in the vimrc file.  Example:
 ---
 --- ```vim
 --- 	if $TERM ==# "xterm"
 --- 	  set background=dark
 --- 	endif
 --- ```
---- When this option is changed, the default settings for the highlight groups
---- will change.  To use other settings, place ":highlight" commands AFTER
---- the setting of the 'background' option.
+--- When this option is changed, the defaults for highlight groups
+--- will change.  To override those defaults, place ":highlight" commands
+--- AFTER setting the 'background' option.
 ---
 --- @type 'light'|'dark'
 vim.o.background = "dark"

runtime/lua/vim/_meta/vimfn.gen.lua

@@ -496,7 +496,7 @@ function vim.fn.browse(save, title, initdir, default) end
 --- @return 0|1
 function vim.fn.browsedir(title, initdir) end
 
---- Adds buffer {name} to the buffer list literally: no special
+--- Adds buffer {name} to the |buffer-list| literally: no special
 --- chars or expansion are applied (including "~"). Returns the
 --- new (or existing matching) buffer number, or 0 on error.
 ---
@@ -504,9 +504,9 @@ function vim.fn.browsedir(title, initdir) end
 --- {name} is an empty string, a new buffer is always created.
 ---
 --- Example (Lua): >lua
----   local b = vim.fn.bufadd(vim.fs.normalize('someName'))
----   vim.bo[b].buflisted = true
----   vim.fn.bufload(b)
+---   local buf = vim.fn.bufadd(vim.fs.normalize('someName'))
+---   -- Set 'buflisted'; trigger BufReadPre/BufReadPost/FileType.
+---   vim.api.nvim_buf_call(buf, vim.cmd.edit)
 --- <
 ---
 --- @param name string
@@ -5247,7 +5247,11 @@ function vim.fn.jobsend(...) end
 ---   pty:        (boolean) Connect the job to a new pseudo
 ---         terminal, and its streams to the master file
 ---         descriptor. `on_stdout` receives all output,
----         `on_stderr` is ignored. |terminal-start|
+---         `on_stderr` is ignored. Note: if the child writes
+---         a query (DA1, OSC, …), it may hang or timeout waiting
+---         for a response! To avoid that, `on_stdout` should
+---         reply via |nvim_chan_send()| on the child's stdin.
+---         See |terminal-start| |terminal-concepts|
 ---   rpc:        (boolean) Use |msgpack-rpc| to communicate with
 ---         the job over stdio. Then `on_stdout` is ignored,
 ---         but `on_stderr` can still be used.
@@ -5258,11 +5262,12 @@ function vim.fn.jobsend(...) end
 ---   stdin:      (string) Either "pipe" (default) to connect the
 ---         job's stdin to a channel or "null" to disconnect
 ---         stdin.
----   term:      (boolean) Spawns {cmd} in a new pseudo-terminal session
----           connected to the current (unmodified) buffer. Implies "pty".
----           Default "height" and "width" are set to the current window
----           dimensions. |jobstart()|. Defaults $TERM to "xterm-256color".
----   width:      (number) Width of the `pty` terminal.
+---   term:       (boolean) Spawns {cmd} in a new pseudo-terminal
+---         session connected to the current (unmodified) buffer.
+---         Implies "pty". Defaults "height" and "width" to the
+---         current window dimensions. Defaults $TERM to
+---         "xterm-256color".
+---   width:      (number) Width of the `pty` pseudo-terminal.
 ---
 --- {opts} is passed as |self| dictionary to the callback; the
 --- caller may set other keys to pass application-specific data.
@@ -8412,14 +8417,13 @@ function vim.fn.setbufline(buf, lnum, text) end
 
 --- Lua: Prefer |nvim_buf_set_var()| or |vim.b| after resolving {buf} to a bufnr; option names use |nvim_set_option_value()|.
 ---
---- Set option or local variable {varname} in buffer {buf} to
---- {val}.
---- This also works for a global or local window option, but it
---- doesn't work for a global or local window variable.
---- For a local window option the global value is unchanged.
+--- Set option or local variable {varname} (string, without "b:")
+--- in buffer {buf} to {val}. Also works for a global or
+--- window-local option (not variable). When targeting
+--- a window-local option, the global option is unchanged.
+---
 --- For the use of {buf}, see |bufname()| above.
---- The {varname} argument is a string.
---- Note that the variable name without "b:" must be used.
+---
 --- Examples: >vim
 ---   call setbufvar(1, "&mod", 1)
 ---   call setbufvar("todo", "myvar", "foobar")

runtime/lua/vim/_meta/vvars.gen.lua

@@ -668,9 +668,9 @@ vim.v.shell_error = ...
 vim.v.stacktrace = ...
 
 --- The reason Nvim started. Possible values:
----   - "normal"    normal startup.
----   - "restart"   started by `:restart`.
----   - "restart!"  started by `:restart!` or `ZR`.
+--- - "normal"    Normal startup, yearning for life, etc.
+--- - "restart"   Started by `:restart`.
+--- - "restart!"  Started by `:restart!` or `ZR`.
 ---
 --- Read-only.
 --- @type string

runtime/lua/vim/fs.lua

@@ -640,7 +640,7 @@ end
 --- On Windows, backslash (\) characters are converted to forward slashes (/).
 ---
 --- Examples:
---- ```lua
+--- ```
 --- [[C:\Users\jdoe]]                         => "C:/Users/jdoe"
 --- "~/src/neovim"                            => "/home/jdoe/src/neovim"
 --- "$XDG_CONFIG_HOME/nvim/init.vim"          => "/Users/jdoe/.config/nvim/init.vim"