docs: misc #32959

9 files changed, 53 insertions, 48 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: