docs: misc #32959

16 files changed, 83 insertions, 72 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 4d368c6426..dae4df00af 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3716,7 +3716,7 @@ nvim_create_augroup({name}, {opts})                    *nvim_create_augroup()*
     Create or get an autocommand group |autocmd-groups|.
 
     To get an existing group id, do: >lua
-        local id = vim.api.nvim_create_augroup("MyGroup", {
+        local id = vim.api.nvim_create_augroup('my.lsp.config', {
             clear = false
         })
 <
@@ -3742,8 +3742,8 @@ nvim_create_autocmd({event}, {opts})                   *nvim_create_autocmd()*
     string).
 
     Example using Lua callback: >lua
-        vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-          pattern = {"*.c", "*.h"},
+        vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
+          pattern = {'*.c', '*.h'},
           callback = function(ev)
             print(string.format('event fired: %s', vim.inspect(ev)))
           end
@@ -3751,15 +3751,15 @@ nvim_create_autocmd({event}, {opts})                   *nvim_create_autocmd()*
 <
 
     Example using an Ex command as the handler: >lua
-        vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-          pattern = {"*.c", "*.h"},
+        vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
+          pattern = {'*.c', '*.h'},
           command = "echo 'Entering a C or C++ file'",
         })
 <
 
     Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|),
     thus names like "$HOME" and "~" must be expanded explicitly: >lua
-        pattern = vim.fn.expand("~") .. "/some/path/*.py"
+        pattern = vim.fn.expand('~') .. '/some/path/*.py'
 <
 
     Attributes: ~
@@ -3881,14 +3881,14 @@ nvim_get_autocmds({opts})                                *nvim_get_autocmds()*
     These examples will get autocommands matching ALL the given criteria: >lua
         -- Matches all criteria
         autocommands = vim.api.nvim_get_autocmds({
-          group = "MyGroup",
-          event = {"BufEnter", "BufWinEnter"},
-          pattern = {"*.c", "*.h"}
+          group = 'MyGroup',
+          event = {'BufEnter', 'BufWinEnter'},
+          pattern = {'*.c', '*.h'}
         })
 
         -- All commands from one group
         autocommands = vim.api.nvim_get_autocmds({
-          group = "MyGroup",
+          group = 'MyGroup',
         })
 <
 
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 21f35637e6..db9a0ad4eb 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -178,8 +178,8 @@ ENVIRONMENT VARIABLES
     • get the server name (use |v:servername| instead)
     • detect a parent Nvim (use |$NVIM| instead)
   • Ignored if --listen is given.
-  • Unset by |terminal| and |jobstart()| unless explicitly given by the "env"
-    option. Example: >vim
+  • Unset at startup (after |v:servername| is initialized). Can be explicitly
+    provided to |terminal| and |jobstart()| by the "env" option. Example: >vim
 	call jobstart(['foo'], { 'env': { 'NVIM_LISTEN_ADDRESS': v:servername  } })
 <
 
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index 51954e5449..6cbc6d3b8e 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -1092,19 +1092,20 @@ CTRL-X CTRL-Z		Stop completion without changing the text.
 
 AUTO-COMPLETION						*compl-autocomplete*
 
-To get basic "autocompletion" without installing a plugin, try this script: >lua
+To get LSP-driven auto-completion, see |lsp-completion|. To get basic
+auto-completion without installing plugins or LSP, try this: >lua
 
-  local triggers = {"."}
-  vim.api.nvim_create_autocmd("InsertCharPre", {
+  local triggers = {'.'}
+  vim.api.nvim_create_autocmd('InsertCharPre', {
     buffer = vim.api.nvim_get_current_buf(),
     callback = function()
-      if vim.fn.pumvisible() == 1 or vim.fn.state("m") == "m" then
+      if vim.fn.pumvisible() == 1 or vim.fn.state('m') == 'm' then
         return
       end
       local char = vim.v.char
       if vim.list_contains(triggers, char) then
-        local key = vim.keycode("<C-x><C-n>")
-        vim.api.nvim_feedkeys(key, "m", false)
+        local key = vim.keycode('<C-x><C-n>')
+        vim.api.nvim_feedkeys(key, 'm', false)
       end
     end
   })
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 50b2559dac..de5ab0849c 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -185,11 +185,14 @@ Example: given the following configs... >lua
 To use LSP features beyond those provided by Nvim (see |lsp-buf|), you can set
 keymaps and options on |Client:on_attach()| or |LspAttach|. Not all language
 servers provide the same capabilities; check `supports_method()` in your
-LspAttach handler. Example: >lua
+LspAttach handler.
+                                                        *lsp-lint* *lsp-format*
+Example: Enable auto-completion and auto-formatting ("linting"): >lua
 
     vim.api.nvim_create_autocmd('LspAttach', {
+      group = vim.api.nvim_create_augroup('my.lsp', {}),
       callback = function(args)
-        local client = vim.lsp.get_client_by_id(args.data.client_id)
+        local client = assert(vim.lsp.get_client_by_id(args.data.client_id))
         if client:supports_method('textDocument/implementation') then
           -- Create a keymap for vim.lsp.buf.implementation ...
         end
@@ -199,12 +202,15 @@ LspAttach handler. Example: >lua
           vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true})
         end
 
-        -- Format the current buffer on save.
-        if client:supports_method('textDocument/formatting') then
+        -- Auto-format ("lint") on save.
+        -- Usually not needed if server supports "textDocument/willSaveWaitUntil".
+        if not client:supports_method('textDocument/willSaveWaitUntil')
+            and client:supports_method('textDocument/formatting') then
           vim.api.nvim_create_autocmd('BufWritePre', {
+            group = vim.api.nvim_create_augroup('my.lsp', {clear=false}),
             buffer = args.buf,
             callback = function()
-              vim.lsp.buf.format({bufnr = args.buf, id = client.id})
+              vim.lsp.buf.format({ bufnr = args.buf, id = client.id, timeout_ms = 1000 })
             end,
           })
         end
@@ -238,21 +244,19 @@ FAQ                                                     *lsp-faq*
      " (async = false is the default for format)
      autocmd BufWritePre *.rs lua vim.lsp.buf.format({ async = false })
 <
-                                                           *lsp-vs-treesitter*
+                                                        *lsp-vs-treesitter*
 - Q: How do LSP and Treesitter compare?
 - A: LSP requires a client and language server. The language server uses
      semantic analysis to understand code at a project level. This provides
      language servers with the ability to rename across files, find
      definitions in external libraries and more.
 
-     Treesitter is a language parsing library that provides excellent tools
+     |treesitter| is a language parsing library that provides excellent tools
      for incrementally parsing text and handling errors. This makes it a great
      fit for editors to understand the contents of the current file for things
      like syntax highlighting, simple goto-definitions, scope analysis and
      more.
 
-     LSP and Treesitter are both great tools for editing and inspecting code.
-
 ================================================================================
 LSP API                                                 *lsp-api*
 
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index 618510fc4f..36ae8fa735 100644
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -185,13 +185,12 @@ clipboard.
 OSC 52 sequences sent from the :terminal buffer do not emit a |TermRequest|
 event. The event is handled directly by Nvim and is not forwarded to plugins.
 
-OSC 133: shell integration			*terminal-osc133*
+OSC 133: shell integration			*terminal-osc133* *shell-prompt*
 
 Shells can emit semantic escape sequences (OSC 133) to mark where each prompt
 starts and ends. The start of a prompt is marked by sequence `OSC 133 ; A ST`,
 and the end by `OSC 133 ; B ST`.
 
-                                                *shell-prompt-config*
 You can configure your shell "rc" (e.g. ~/.bashrc) to emit OSC 133 sequences,
 or your terminal may attempt to do it for you (assuming your shell config
 doesn't interfere).
@@ -214,6 +213,9 @@ emits OSC 133 as described above.
 To annotate each terminal prompt with a sign, call |nvim_buf_set_extmark()|
 from a |TermRequest| handler: >lua
 
+    vim.api.nvim_create_autocmd('TermOpen', {
+      command = 'setlocal signcolumn=auto',
+    })
     local ns = vim.api.nvim_create_namespace('my.terminal.prompt')
     vim.api.nvim_create_autocmd('TermRequest', {
       callback = function(args)
@@ -226,10 +228,6 @@ from a |TermRequest| handler: >lua
         end
       end,
     })
-    -- Enable signcolumn in terminal buffers.
-    vim.api.nvim_create_autocmd('TermOpen', {
-      command = 'setlocal signcolumn=auto',
-    })
 <
 ==============================================================================
 Status Variables				*terminal-status*
diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt
index 18b09be3a2..ec7dfe4d4b 100644
--- a/runtime/doc/vvars.txt
+++ b/runtime/doc/vvars.txt
@@ -563,8 +563,9 @@ v:servername
 		Read-only.
 
 		                                                     *$NVIM*
-		$NVIM is set by |terminal| and |jobstart()|, and is thus
-		a hint that the current environment is a subprocess of Nvim.
+		$NVIM is set to v:servername by |terminal| and |jobstart()|,
+		and is thus a hint that the current environment is a child
+		(direct subprocess) of Nvim.
 
 		Example: a child Nvim process can detect and make requests to
 		its parent Nvim: >lua
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index e29d8f1c30..c9b8e68c10 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -8,7 +8,7 @@
 --       - "opt-in": runtime/pack/dist/opt/
 --    2. runtime/lua/vim/ (the runtime): Lazy-loaded modules. Examples: `inspect`, `lpeg`.
 --    3. runtime/lua/vim/shared.lua: pure Lua functions which always are available. Used in the test
---       runner, as well as worker threads and processes launched from Nvim.
+--       runner, and worker threads/processes launched from Nvim.
 --    4. runtime/lua/vim/_editor.lua: Eager-loaded code which directly interacts with the Nvim
 --       editor state. Only available in the main thread.
 --
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index ece3c1854b..2c1fb260b2 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -885,7 +885,7 @@ function vim.api.nvim_command_output(command) end
 --- To get an existing group id, do:
 ---
 --- ```lua
---- local id = vim.api.nvim_create_augroup("MyGroup", {
+--- local id = vim.api.nvim_create_augroup('my.lsp.config', {
 ---     clear = false
 --- })
 --- ```
@@ -904,8 +904,8 @@ function vim.api.nvim_create_augroup(name, opts) end
 --- Example using Lua callback:
 ---
 --- ```lua
---- vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
----   pattern = {"*.c", "*.h"},
+--- vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
+---   pattern = {'*.c', '*.h'},
 ---   callback = function(ev)
 ---     print(string.format('event fired: %s', vim.inspect(ev)))
 ---   end
@@ -915,8 +915,8 @@ function vim.api.nvim_create_augroup(name, opts) end
 --- Example using an Ex command as the handler:
 ---
 --- ```lua
---- vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
----   pattern = {"*.c", "*.h"},
+--- vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
+---   pattern = {'*.c', '*.h'},
 ---   command = "echo 'Entering a C or C++ file'",
 --- })
 --- ```
@@ -925,7 +925,7 @@ function vim.api.nvim_create_augroup(name, opts) end
 --- and "~" must be expanded explicitly:
 ---
 --- ```lua
---- pattern = vim.fn.expand("~") .. "/some/path/*.py"
+--- pattern = vim.fn.expand('~') .. '/some/path/*.py'
 --- ```
 ---
 --- @see `:help autocommand`
@@ -1222,14 +1222,14 @@ function vim.api.nvim_get_all_options_info() end
 --- ```lua
 --- -- Matches all criteria
 --- autocommands = vim.api.nvim_get_autocmds({
----   group = "MyGroup",
----   event = {"BufEnter", "BufWinEnter"},
----   pattern = {"*.c", "*.h"}
+---   group = 'MyGroup',
+---   event = {'BufEnter', 'BufWinEnter'},
+---   pattern = {'*.c', '*.h'}
 --- })
 ---
 --- -- All commands from one group
 --- autocommands = vim.api.nvim_get_autocmds({
----   group = "MyGroup",
+---   group = 'MyGroup',
 --- })
 --- ```
 ---
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index 9df5a0b5f2..25e504a612 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -586,8 +586,9 @@ vim.v.searchforward = ...
 --- Read-only.
 ---
 ---                                                      *$NVIM*
---- $NVIM is set by `terminal` and `jobstart()`, and is thus
---- a hint that the current environment is a subprocess of Nvim.
+--- $NVIM is set to v:servername by `terminal` and `jobstart()`,
+--- and is thus a hint that the current environment is a child
+--- (direct subprocess) of Nvim.
 ---
 --- Example: a child Nvim process can detect and make requests to
 --- its parent Nvim:
diff --git a/src/gen/gen_api_dispatch.lua b/src/gen/gen_api_dispatch.lua
index a5d0890c2f..b5433527bc 100644
--- a/src/gen/gen_api_dispatch.lua
+++ b/src/gen/gen_api_dispatch.lua
@@ -1,3 +1,5 @@
+-- Generates C code to bridge API <=> Lua.
+--
 -- Example (manual) invocation:
 --
 --    make
@@ -192,7 +194,7 @@ for _, f in ipairs(shallowcopy(functions)) do
           .. ' has deprecated alias\n'
           .. newname
           .. ' which has a separate implementation.\n'
-          .. 'Please remove it from src/nvim/api/dispatch_deprecated.lua'
+          .. 'Remove it from src/nvim/api/dispatch_deprecated.lua'
       )
       os.exit(1)
     end
@@ -729,6 +731,10 @@ output:write('\n')
 
 local lua_c_functions = {}
 
+--- Generates C code to bridge RPC API <=> Lua.
+---
+--- Inspect the result here:
+---    build/src/nvim/auto/api/private/dispatch_wrappers.generated.h
 local function process_function(fn)
   local lua_c_function_name = ('nlua_api_%s'):format(fn.name)
   write_shifted_output(
diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index d436dbb7f1..1e33b0b62a 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -53,14 +53,14 @@ static int64_t next_autocmd_id = 1;
 /// ```lua
 /// -- Matches all criteria
 /// autocommands = vim.api.nvim_get_autocmds({
-///   group = "MyGroup",
-///   event = {"BufEnter", "BufWinEnter"},
-///   pattern = {"*.c", "*.h"}
+///   group = 'MyGroup',
+///   event = {'BufEnter', 'BufWinEnter'},
+///   pattern = {'*.c', '*.h'}
 /// })
 ///
 /// -- All commands from one group
 /// autocommands = vim.api.nvim_get_autocmds({
-///   group = "MyGroup",
+///   group = 'MyGroup',
 /// })
 /// ```
 ///
@@ -336,8 +336,8 @@ cleanup:
 /// Example using Lua callback:
 ///
 /// ```lua
-/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-///   pattern = {"*.c", "*.h"},
+/// vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
+///   pattern = {'*.c', '*.h'},
 ///   callback = function(ev)
 ///     print(string.format('event fired: %s', vim.inspect(ev)))
 ///   end
@@ -347,8 +347,8 @@ cleanup:
 /// Example using an Ex command as the handler:
 ///
 /// ```lua
-/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-///   pattern = {"*.c", "*.h"},
+/// vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
+///   pattern = {'*.c', '*.h'},
 ///   command = "echo 'Entering a C or C++ file'",
 /// })
 /// ```
@@ -357,7 +357,7 @@ cleanup:
 /// and "~" must be expanded explicitly:
 ///
 /// ```lua
-/// pattern = vim.fn.expand("~") .. "/some/path/*.py"
+/// pattern = vim.fn.expand('~') .. '/some/path/*.py'
 /// ```
 ///
 /// @param event (string|array) Event(s) that will trigger the handler (`callback` or `command`).
@@ -603,7 +603,7 @@ void nvim_clear_autocmds(Dict(clear_autocmds) *opts, Arena *arena, Error *err)
 /// To get an existing group id, do:
 ///
 /// ```lua
-/// local id = vim.api.nvim_create_augroup("MyGroup", {
+/// local id = vim.api.nvim_create_augroup('my.lsp.config', {
 ///     clear = false
 /// })
 /// ```
diff --git a/src/nvim/channel.c b/src/nvim/channel.c
index 9fc0a82ca3..899add944e 100644
--- a/src/nvim/channel.c
+++ b/src/nvim/channel.c
@@ -514,8 +514,7 @@ void channel_from_connection(SocketWatcher *watcher)
   channel_create_event(channel, watcher->addr);
 }
 
-/// Creates an API channel from stdin/stdout. This is used when embedding
-/// Neovim
+/// Creates an API channel from stdin/stdout. Used when embedding Nvim.
 uint64_t channel_from_stdio(bool rpc, CallbackReader on_output, const char **error)
   FUNC_ATTR_NONNULL_ALL
 {
diff --git a/src/nvim/eval/funcs.c b/src/nvim/eval/funcs.c
index 587b3a9c88..03713aa262 100644
--- a/src/nvim/eval/funcs.c
+++ b/src/nvim/eval/funcs.c
@@ -3834,6 +3834,7 @@ static const char *pty_ignored_env_vars[] = {
   "COLORFGBG",
   "COLORTERM",
 #endif
+  // Nvim-owned env vars. #6764
   "VIM",
   "VIMRUNTIME",
   NULL
@@ -3870,9 +3871,8 @@ dict_T *create_environment(const dictitem_T *job_env, const bool clear_env, cons
     tv_dict_free(temp_env.vval.v_dict);
 
     if (pty) {
-      // These environment variables generally shouldn't be propagated to the
-      // child process.  We're removing them here so the user can still decide
-      // they want to explicitly set them.
+      // These env vars shouldn't propagate to the child process. #6764
+      // Remove them here, then the user may decide to explicitly set them below.
       for (size_t i = 0;
            i < ARRAY_SIZE(pty_ignored_env_vars) && pty_ignored_env_vars[i];
            i++) {
diff --git a/src/nvim/main.c b/src/nvim/main.c
index 926ad8ca31..7539fbc5d9 100644
--- a/src/nvim/main.c
+++ b/src/nvim/main.c
@@ -165,7 +165,7 @@ void event_init(void)
 }
 
 /// @returns false if main_loop could not be closed gracefully
-bool event_teardown(void)
+static bool event_teardown(void)
 {
   if (!main_loop.events) {
     input_stop();
diff --git a/src/nvim/vvars.lua b/src/nvim/vvars.lua
index cb84df015c..5de617b5cb 100644
--- a/src/nvim/vvars.lua
+++ b/src/nvim/vvars.lua
@@ -674,8 +674,9 @@ M.vars = {
       Read-only.
 
                                                            *$NVIM*
-      $NVIM is set by |terminal| and |jobstart()|, and is thus
-      a hint that the current environment is a subprocess of Nvim.
+      $NVIM is set to v:servername by |terminal| and |jobstart()|,
+      and is thus a hint that the current environment is a child
+      (direct subprocess) of Nvim.
 
       Example: a child Nvim process can detect and make requests to
       its parent Nvim: >lua
diff --git a/test/functional/core/job_spec.lua b/test/functional/core/job_spec.lua
index 5697dbc56f..7f984b1e24 100644
--- a/test/functional/core/job_spec.lua
+++ b/test/functional/core/job_spec.lua
@@ -713,7 +713,7 @@ describe('jobs', function()
   end)
 
   it('jobstart() environment: $NVIM, $NVIM_LISTEN_ADDRESS #11009', function()
-    local function get_env_in_child_job(envname, env)
+    local function get_child_env(envname, env)
       return exec_lua(
         [[
         local envname, env = ...
@@ -741,17 +741,17 @@ describe('jobs', function()
     -- $NVIM is _not_ defined in the top-level Nvim process.
     eq('', eval('$NVIM'))
     -- jobstart() shares its v:servername with the child via $NVIM.
-    eq('NVIM=' .. addr, get_env_in_child_job('NVIM'))
+    eq('NVIM=' .. addr, get_child_env('NVIM'))
     -- $NVIM_LISTEN_ADDRESS is unset by server_init in the child.
-    eq('NVIM_LISTEN_ADDRESS=v:null', get_env_in_child_job('NVIM_LISTEN_ADDRESS'))
+    eq('NVIM_LISTEN_ADDRESS=v:null', get_child_env('NVIM_LISTEN_ADDRESS'))
     eq(
       'NVIM_LISTEN_ADDRESS=v:null',
-      get_env_in_child_job('NVIM_LISTEN_ADDRESS', { NVIM_LISTEN_ADDRESS = 'Xtest_jobstart_env' })
+      get_child_env('NVIM_LISTEN_ADDRESS', { NVIM_LISTEN_ADDRESS = 'Xtest_jobstart_env' })
     )
     -- User can explicitly set $NVIM_LOG_FILE, $VIM, $VIMRUNTIME.
     eq(
       'NVIM_LOG_FILE=Xtest_jobstart_env',
-      get_env_in_child_job('NVIM_LOG_FILE', { NVIM_LOG_FILE = 'Xtest_jobstart_env' })
+      get_child_env('NVIM_LOG_FILE', { NVIM_LOG_FILE = 'Xtest_jobstart_env' })
     )
     os.remove('Xtest_jobstart_env')
   end)