docs: autocmds, misc

13 files changed, 64 insertions, 54 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 8c79279361..3a3d939cd7 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -209,7 +209,7 @@ any of these approaches:
      nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)'
 <
   3. Use the |api_info()| Vimscript function. >vim
-     :lua print(vim.inspect(vim.fn.api_info()))
+     :lua vim.print(vim.fn.api_info())
 <     Example using |filter()| to exclude non-deprecated API functions: >vim
      :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
 
@@ -2030,7 +2030,7 @@ whether a buffer is loaded.
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
     Activates buffer-update events on a channel, or as Lua callbacks.
 
-    Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua
+    Example (Lua): capture buffer updates in a global `events` variable (use "vim.print(events)" to see its contents): >lua
       events = {}
       vim.api.nvim_buf_attach(0, false, {
         on_lines=function(...) table.insert(events, {...}) end})
@@ -2554,7 +2554,7 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
       local ms  = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
       -- Get all marks in this buffer + namespace.
       local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
-      print(vim.inspect(ms))
+      vim.print(ms)
 <
 
     Parameters: ~
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index a782be65e7..ffa7d6282a 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -212,28 +212,27 @@ events.
 Nvim recognizes the following events.  Names are case-insensitive.
 
 							*BufAdd*
-BufAdd				Just after creating a new buffer which is
-				added to the buffer list, or adding a buffer
-				to the buffer list, a buffer in the buffer
-				list was renamed.
-				Not triggered for the initial buffers created
-				during startup.
+BufAdd				After adding a new buffer or existing unlisted
+				buffer to the buffer list (except during
+				startup, see |VimEnter|), or renaming a listed
+				buffer.
 				Before |BufEnter|.
-				NOTE: Current buffer "%" may be different from
-				the buffer being created "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 							*BufDelete*
 BufDelete			Before deleting a buffer from the buffer list.
 				The BufUnload may be called first (if the
 				buffer was loaded).
 				Also used just before a buffer in the buffer
 				list is renamed.
-				NOTE: Current buffer "%" may be different from
-				the buffer being deleted "<afile>" and "<abuf>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Do not change to another buffer.
 							*BufEnter*
-BufEnter			After entering a buffer.  Useful for setting
-				options for a file type.  Also executed when
-				starting to edit a buffer.
+BufEnter			After entering (visiting, switching-to) a new
+				or existing buffer. Useful for setting
+				filetype options.  Compare |BufNew| which
+				does not trigger for existing buffers.
 				After |BufAdd|.
 				After |BufReadPost|.
 							*BufFilePost*
@@ -248,8 +247,8 @@ BufHidden			Before a buffer becomes hidden: when there are
 				the buffer is not unloaded or deleted.
 
 				Not used for ":qa" or ":q" when exiting Vim.
-				NOTE: current buffer "%" may be different from
-				the buffer being unloaded "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 							*BufLeave*
 BufLeave			Before leaving to another buffer.  Also when
 				leaving or closing the current window and the
@@ -260,12 +259,14 @@ BufLeave			Before leaving to another buffer.  Also when
 BufModifiedSet			After the `'modified'` value of a buffer has
 				been changed.
 							*BufNew*
-BufNew				Just after creating a new buffer.  Also used
-				just after a buffer has been renamed.  When
-				the buffer is added to the buffer list BufAdd
-				will be triggered too.
-				NOTE: Current buffer "%" may be different from
-				the buffer being created "<afile>".
+BufNew				After creating a new buffer (except during
+				startup, see |VimEnter|) or renaming an
+				existing buffer. Unlike |BufEnter|, visiting
+				(switching to) an existing buffer will not
+				trigger this again.
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
+				See also |BufAdd|, |BufNewFile|.
 							*BufNewFile*
 BufNewFile			When starting to edit a file that doesn't
 				exist.  Can be used to read in a skeleton
@@ -298,8 +299,8 @@ BufUnload			Before unloading a buffer, when the text in
 				Before BufDelete.
 				Triggers for all loaded buffers when Vim is
 				going to exit.
-				NOTE: Current buffer "%" may be different from
-				the buffer being unloaded "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Do not switch buffers or windows!
 				Not triggered when exiting and v:dying is 2 or
 				more.
@@ -319,8 +320,8 @@ BufWinLeave			Before a buffer is removed from a window.
 				Not when it's still visible in another window.
 				Also triggered when exiting.
 				Before BufUnload, BufHidden.
-				NOTE: Current buffer "%" may be different from
-				the buffer being unloaded "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Not triggered when exiting and v:dying is 2 or
 				more.
 							*BufWipeout*
@@ -330,8 +331,8 @@ BufWipeout			Before completely deleting a buffer.  The
 				buffer list).  Also used just before a buffer
 				is renamed (also when it's not in the buffer
 				list).
-				NOTE: Current buffer "%" may be different from
-				the buffer being deleted "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>", "<abuf>". |<buffer=abuf>|
 				Do not change to another buffer.
 						*BufWrite* *BufWritePre*
 BufWrite or BufWritePre		Before writing the whole buffer to a file.
@@ -597,8 +598,8 @@ FileChangedShell		When Vim notices that the modification time of
 				prompt is not given.
 				|v:fcs_reason| indicates what happened. Set
 				|v:fcs_choice| to control what happens next.
-				NOTE: Current buffer "%" may be different from
-				the buffer that was changed "<afile>".
+				NOTE: Current buffer "%" is not the target
+				buffer "<afile>" and "<abuf>". |<buffer=abuf>|
 							*E246* *E811*
 				Cannot switch, jump to or delete buffers.
 				Non-recursive (event cannot trigger itself).
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 1cbc9135d3..c8d1d0b25b 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -656,7 +656,7 @@ api_info()						*api_info()*
 		Returns Dictionary of |api-metadata|.
 
 		View it in a nice human-readable format: >
-		       :lua print(vim.inspect(vim.fn.api_info()))
+		       :lua vim.print(vim.fn.api_info())
 
 append({lnum}, {text})					*append()*
 		When {text} is a |List|: Append each item of the |List| as a
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 9b168cb9cd..42600e405c 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -154,16 +154,17 @@ The `vim.lsp.buf_…` functions perform operations for all LSP clients attached
 to the given buffer. |lsp-buf|
 
 LSP request/response handlers are implemented as Lua functions (see
-|lsp-handler|). The |vim.lsp.handlers| table defines default handlers used
-when creating a new client. Keys are LSP method names: >vim
-
-    :lua print(vim.inspect(vim.tbl_keys(vim.lsp.handlers)))
-<
+|lsp-handler|).
                                                                   *lsp-method*
 
-Methods are the names of requests and notifications as defined by the LSP
-specification. These LSP requests/notifications are defined by default in the
-Nvim LSP client (but depends on server support):
+Requests and notifications defined by the LSP specification are referred to as
+"LSP methods". The Nvim LSP client provides default handlers in the global
+|vim.lsp.handlers| table, you can list them with this command: >vim
+
+    :lua vim.print(vim.tbl_keys(vim.lsp.handlers))
+<
+They are also listed below. Note that handlers depend on server support: they
+won't run if your server doesn't support them.
 
 - callHierarchy/incomingCalls
 - callHierarchy/outgoingCalls
@@ -190,8 +191,11 @@ Nvim LSP client (but depends on server support):
 - window/showDocument
 - window/showMessageRequest
 - workspace/applyEdit
+- workspace/configuration
+- workspace/executeCommand
 - workspace/inlayHint/refresh
 - workspace/symbol
+- workspace/workspaceFolders
 
                                                                  *lsp-handler*
 LSP handlers are functions that handle |lsp-response|s to requests made by Nvim
diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt
index 22f51ce8c7..af7f22304d 100644
--- a/runtime/doc/lua-guide.txt
+++ b/runtime/doc/lua-guide.txt
@@ -218,7 +218,7 @@ Vimscript are automatically converted:
     print(vim.fn.printf('Hello from %s', 'Lua'))
 
     local reversed_list = vim.fn.reverse({ 'a', 'b', 'c' })
-    print(vim.inspect(reversed_list)) -- { "c", "b", "a" }
+    vim.print(reversed_list) -- { "c", "b", "a" }
 
     local function print_stdout(chan_id, data, name)
       print(data[1])
@@ -261,7 +261,7 @@ Data types are converted automatically. For example:
       key2 = 300
     }
 
-    print(vim.inspect(vim.g.some_global_variable))
+    vim.print(vim.g.some_global_variable)
     --> { key1 = "value", key2 = 300 }
 <
 You can target specific buffers (via number), windows (via |window-ID|), or
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index c3eaf1ae39..822ce4e85a 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -14,7 +14,7 @@ INTRODUCTION                                                       *lua-intro*
 The Lua 5.1 script engine is builtin and always available. Try this command to
 get an idea of what lurks beneath: >vim
 
-    :lua print(vim.inspect(package.loaded))
+    :lua vim.print(package.loaded)
 
 Nvim includes a "standard library" |lua-stdlib| for Lua.  It complements the
 "editor stdlib" (|builtin-functions| and |Ex-commands|) and the |API|, all of
@@ -423,7 +423,7 @@ is unnecessary.
 
 You can peek at the module properties: >vim
 
-    :lua print(vim.inspect(vim))
+    :lua vim.print(vim)
 
 Result is something like this: >
 
@@ -1414,6 +1414,7 @@ inspect({object}, {options})                                   *vim.inspect()*
     Gets a human-readable representation of the given object.
 
     See also: ~
+      • |vim.print()|
       • https://github.com/kikito/inspect.lua
       • https://github.com/mpeterv/vinspect
 
@@ -1538,6 +1539,7 @@ print({...})                                                     *vim.print()*
 
     See also: ~
       • |vim.inspect()|
+      • |:=|
 
 region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})         *vim.region()*
     Get a table of lines with start, end columns for a region marked by two
@@ -3172,7 +3174,7 @@ Iter:find({self}, {f})                                           *Iter:find()*
         any
 
 Iter:fold({self}, {init}, {f})                                   *Iter:fold()*
-    Fold an iterator or table into a single value.
+    Fold ("reduce") an iterator or table into a single value.
 
     Examples: >lua
 
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 4e2ee14537..1b1dca321b 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -171,8 +171,8 @@ g8			Print the hex values of the bytes used in the
 			Like ":z" or ":z!", but number the lines.
 
 							*:=*
-:=			Without arg: Print the last line number.
-			with args: equivalent to `:lua ={expr}`. see |:lua|
+:= [args]		Without [args]: prints the last line number.
+			With [args]: equivalent to `:lua ={expr}`. see |:lua|
 
 :{range}=		Prints the last line number in {range}.  For example,
 			this prints the current line number: >
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index c44595f237..686905537d 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -459,8 +459,9 @@ Lua interface (|lua.txt|):
 - `:lua print("a\0b")` will print `a^@b`, like with `:echomsg "a\nb"` . In Vim
   that prints `a` and `b` on separate lines, exactly like
   `:lua print("a\nb")` .
-- `:lua error('TEST')` emits the error “E5105: Error while calling Lua chunk:
-  [string "<Vimscript compiled string>"]:1: TEST”, whereas Vim emits only “TEST”.
+- `:lua error('TEST')` emits the error: >
+  E5108: Error executing lua: [string "<Vimscript compiled string>"]:1: TEST
+<  whereas Vim emits only "TEST".
 - Lua has direct access to Nvim |API| via `vim.api`.
 - Lua package.path and package.cpath are automatically updated according to
   'runtimepath': |lua-require|.
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index e2ed0d980e..ab20c36b17 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -184,6 +184,7 @@ end
 
 --- Gets a human-readable representation of the given object.
 ---
+---@see |vim.print()|
 ---@see https://github.com/kikito/inspect.lua
 ---@see https://github.com/mpeterv/vinspect
 local function inspect(object, options) -- luacheck: no unused
@@ -870,6 +871,7 @@ end
 --- </pre>
 ---
 --- @see |vim.inspect()|
+--- @see |:=|
 --- @return any # given arguments.
 function vim.print(...)
   if vim.in_fast_event() then
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index 970bb56478..a8e75c4dc9 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -2457,7 +2457,7 @@ end
 ---                   buffer number as arguments. Example:
 ---             <pre>lua
 ---               vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
----                 print(vim.inspect(client))
+---                 vim.print(client)
 ---               end)
 ---             </pre>
 ---@deprecated use lsp.get_active_clients({ bufnr = bufnr }) with regular loop
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index b40f8526ea..96db0d1aad 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -2,7 +2,7 @@
 """Generates Nvim :help docs from C/Lua docstrings, using Doxygen.
 
 Also generates *.mpack files. To inspect the *.mpack structure:
-    :new | put=v:lua.vim.inspect(v:lua.vim.mpack.unpack(readfile('runtime/doc/api.mpack','B')))
+    :new | put=v:lua.vim.inspect(v:lua.vim.mpack.decode(readfile('runtime/doc/api.mpack','B')))
 
 Flow:
     main
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 4c3faf8d8b..c1aef53dc0 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -84,7 +84,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
 /// Activates buffer-update events on a channel, or as Lua callbacks.
 ///
 /// Example (Lua): capture buffer updates in a global `events` variable
-/// (use "print(vim.inspect(events))" to see its contents):
+/// (use "vim.print(events)" to see its contents):
 /// <pre>lua
 ///   events = {}
 ///   vim.api.nvim_buf_attach(0, false, {
diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c
index a101e1bbf1..0608a8961d 100644
--- a/src/nvim/api/extmark.c
+++ b/src/nvim/api/extmark.c
@@ -320,7 +320,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
 ///   local ms  = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
 ///   -- Get all marks in this buffer + namespace.
 ///   local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
-///   print(vim.inspect(ms))
+///   vim.print(ms)
 /// </pre>
 ///
 /// @param buffer  Buffer handle, or 0 for current buffer