docs #20986

- https://github.com/neovim/tree-sitter-vimdoc v1.2.4 eliminates most
  errors in pi_netrw.txt, so we can remove that workaround from
  ignore_parse_error().
- improved codeblock

13 files changed, 156 insertions, 195 deletions

diff --git a/README.md b/README.md
index 7f06455cfc..227b028c01 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
   <img src="https://raw.githubusercontent.com/neovim/neovim.github.io/master/logos/neovim-logo-300x87.png" alt="Neovim">
 </h1>
 
-[Documentation](https://neovim.io/doc/general/) |
+[Documentation](https://neovim.io/doc/) |
 [Chat](https://app.element.io/#/room/#neovim:matrix.org) |
 [Twitter](https://twitter.com/Neovim)
 
@@ -107,9 +107,9 @@ Apache 2.0 license, except for contributions copied from Vim (identified by the
     encouraged to make a donation for needy children in Uganda.  Please see the
     kcc section of the vim docs or visit the ICCF web site, available at these URLs:
 
-            http://iccf-holland.org/
-            http://www.vim.org/iccf/
-            http://www.iccf.nl/
+            https://iccf-holland.org/
+            https://www.vim.org/iccf/
+            https://www.iccf.nl/
 
     You can also sponsor the development of Vim.  Vim sponsors can vote for
     features.  The money goes to Uganda anyway.
@@ -121,7 +121,7 @@ Apache 2.0 license, except for contributions copied from Vim (identified by the
 [advanced UIs]: https://github.com/neovim/neovim/wiki/Related-projects#gui
 [Managed packages]: https://github.com/neovim/neovim/wiki/Installing-Neovim#install-from-package
 [Debian]: https://packages.debian.org/testing/neovim
-[Ubuntu]: http://packages.ubuntu.com/search?keywords=neovim
+[Ubuntu]: https://packages.ubuntu.com/search?keywords=neovim
 [Fedora]: https://packages.fedoraproject.org/pkgs/neovim/neovim/
 [Arch Linux]: https://www.archlinux.org/packages/?q=neovim
 [Void Linux]: https://voidlinux.org/packages/?arch=x86_64&q=neovim
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index decd3ca7d3..6659e9b79b 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3228,89 +3228,54 @@ nvim_create_augroup({name}, {*opts})                   *nvim_create_augroup()*
         |autocmd-groups|
 
 nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
-    Create an |autocommand|
-
-    The API allows for two (mutually exclusive) types of actions to be
-    executed when the autocommand triggers: a callback function (Lua or
-    Vimscript), or a command (like regular autocommands).
-
-    Example using callback: >lua
-        -- Lua function
-        local myluafun = function() print("This buffer enters") end
-
-        -- Vimscript function name (as a string)
-        local myvimfun = "g:MyVimFunction"
+    Creates an |autocommand| event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string).
 
+    Example using Lua callback: >lua
         vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
           pattern = {"*.c", "*.h"},
-          callback = myluafun,  -- Or myvimfun
+          callback = function(ev)
+            print(string.format('event fired: s', vim.inspect(ev)))
+          end
         })
 <
 
-    Lua functions receive a table with information about the autocmd event as
-    an argument. To use a function which itself accepts another (optional)
-    parameter, wrap the function in a lambda: >lua
-        -- Lua function with an optional parameter.
-        -- The autocmd callback would pass a table as argument but this
-        -- function expects number|nil
-        local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
-
-        vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-          pattern = {"*.c", "*.h"},
-          callback = function() myluafun() end,
-        })
-<
-
-    Example using command: >lua
+    Example using an Ex command as the handler: >lua
         vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
           pattern = {"*.c", "*.h"},
           command = "echo 'Entering a C or C++ file'",
         })
 <
 
-    Example values for pattern: >lua
-      pattern = "*.py"
-      pattern = { "*.py", "*.pyi" }
-<
-
-    Note: The `pattern` is passed to callbacks and commands as a literal string; environment
-    variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead,
-    |expand()| such variables explicitly: >lua
+    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"
 <
 
-    Example values for event: >lua
-      event = "BufWritePre"
-      event = {"CursorHold", "BufWritePre", "BufWritePost"}
-<
-
     Parameters: ~
-      • {event}  (string|array) The event or events to register this
-                 autocommand
-      • {opts}   Dictionary of autocommand options:
-                 • group (string|integer) optional: the autocommand group name
-                   or id to match against.
-                 • pattern (string|array) optional: pattern or patterns to
-                   match literally against |autocmd-pattern|.
-                 • buffer (integer) optional: buffer number for buffer local
+      • {event}  (string|array) Event(s) that will trigger the handler
+                 (`callback` or `command`).
+      • {opts}   Options dict:
+                 • group (string|integer) optional: autocommand group name or
+                   id to match against.
+                 • pattern (string|array) optional: pattern(s) to match
+                   literally |autocmd-pattern|.
+                 • buffer (integer) optional: buffer number for buffer-local
                    autocommands |autocmd-buflocal|. Cannot be used with
                    {pattern}.
-                 • desc (string) optional: description of the autocommand.
-                 • callback (function|string) optional: if a string, the name
-                   of a Vimscript function to call when this autocommand is
-                   triggered. Otherwise, a Lua function which is called when
-                   this autocommand is triggered. Cannot be used with
-                   {command}. Lua callbacks can return true to delete the
-                   autocommand; in addition, they accept a single table
-                   argument with the following keys:
-                   • id: (number) the autocommand id
-                   • event: (string) the name of the event that triggered the
-                     autocommand |autocmd-events|
-                   • group: (number|nil) the autocommand group id, if it
-                     exists
-                   • match: (string) the expanded value of |<amatch>|
-                   • buf: (number) the expanded value of |<abuf>|
-                   • file: (string) the expanded value of |<afile>|
+                 • desc (string) optional: description (for documentation and
+                   troubleshooting).
+                 • callback (function|string) optional: Lua function (or
+                   Vimscript function name, if string) called when the
+                   event(s) is triggered. Lua callback can return true to
+                   delete the autocommand, and receives a table argument with
+                   these keys:
+                   • id: (number) autocommand id
+                   • event: (string) name of the triggered event
+                     |autocmd-events|
+                   • group: (number|nil) autocommand group id, if any
+                   • match: (string) expanded value of |<amatch>|
+                   • buf: (number) expanded value of |<abuf>|
+                   • file: (string) expanded value of |<afile>|
                    • data: (any) arbitrary data passed to
                      |nvim_exec_autocmds()|
 
@@ -3322,7 +3287,7 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
                    autocommands |autocmd-nested|.
 
     Return: ~
-        Integer id of the created autocommand.
+        Autocommand id (number)
 
     See also: ~
         |autocommand|
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 9336321d73..ff48ae3e26 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -28,11 +28,9 @@ The Neo bits of Nvim should make it a better Vim, without becoming a
 completely different editor.
 - In matters of taste, prefer Vim/Unix tradition. If there is no relevant
   Vim/Unix tradition, consider the "common case".
-- A feature that people do not know about is a useless feature.  Don't add
-  obscure features, or at least add hints in documentation that they exist.
-- There is no limit to the features that can be added.  Selecting new features
-  is based on (1) what users ask for, (2) how much effort it takes to
-  implement and (3) someone actually implementing it.
+- There is no limit to the features that can be added.  Select new features
+  based on (1) what users ask for, (2) how much effort it takes to implement
+  and (3) someone actually implementing it.
 - Backwards compatibility is a feature.  The RPC API in particular should
   never break.
 
@@ -48,7 +46,7 @@ NVIM IS... WELL DOCUMENTED				*design-documented*
 
 NVIM IS... FAST AND SMALL				*design-speed-size*
 
-Keep Nvim small and fast.
+Keep Nvim small and fast. This directly affects versatility and usability.
 - Computers are becoming faster and bigger each year.  Vim can grow too, but
   no faster than computers are growing.  Keep Vim usable on older systems.
 - Many users start Vim from a shell very often.  Startup time must be short.
@@ -57,7 +55,8 @@ Keep Nvim small and fast.
 - Don't forget that some people use Vim over a slow connection.  Minimize the
   communication overhead.
 - Vim is a component among other components.  Don't turn it into a massive
-  application, but have it work well together with other programs.
+  application, but have it work well together with other programs
+  ("composability").
 
 
 NVIM IS... MAINTAINABLE					*design-maintain*
@@ -250,13 +249,25 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
 LUA							*dev-lua*
 
 - Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or
-  pseudo-OOP designs. Plugin authors just want functions to call, they don't
-  want to learn a big, fancy inheritance hierarchy. Thus avoid specialized
-  objects; tables or values are usually better.
+  pseudo-OOP designs. Plugin authors just want functions to call, not a big,
+  fancy inheritance hierarchy.
+- Avoid requiring or returning special objects in the Nvim stdlib. Plain
+  tables or values are easier to serialize, easier to construct from literals,
+  easier to inspect and print, and inherently compatible with all Lua plugins.
+  (This guideline doesn't apply to opaque, non-data objects like `vim.cmd`.)
 
 
 API							*dev-api*
 
+- Avoid "mutually exclusive" parameters--via constraints or limitations, if
+  necessary. For example nvim_create_autocmd() has mutually exclusive
+  "callback" and "command" args; but the "command" arg could be eliminated by
+  simply not supporting Vimscript function names, and treating a string
+  "callback" arg as an Ex command (which can call Vimscript functions). The
+  "buffer" arg could also be eliminated by treating a number "pattern" as
+  a buffer number.
+
+                                                              *dev-api-naming*
 Use this format to name new RPC |API| functions:
 
     nvim_{thing}_{action}_{arbitrary-qualifiers}
diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
index 3cfc3429de..13b953ed60 100644
--- a/runtime/doc/editing.txt
+++ b/runtime/doc/editing.txt
@@ -423,9 +423,8 @@ Note that such expressions are only supported in places where a filename is
 expected as an argument to an Ex-command.
 
 							*++opt* *[++opt]*
-The [++opt] argument can be used to force the value of 'fileformat',
-'fileencoding' or 'binary' to a value for one command, and to specify the
-behavior for bad characters.  The form is: >
+The [++opt] argument can be used to set some options for one command, and to
+specify the behavior for bad characters.  The form is: >
 	++{optname}
 Or: >
 	++{optname}={value}
@@ -436,13 +435,11 @@ Where {optname} is one of:	    *++ff* *++enc* *++bin* *++nobin* *++edit*
     bin    or  binary	    sets 'binary'
     nobin  or  nobinary	    resets 'binary'
     bad			    specifies behavior for bad characters
-    edit		    for |:read| only: keep option values as if editing
-			    a file
-    p			    creates the parent directory (or directories) of
-			    a filename if they do not exist
+    edit		    for |:read|: keeps options as if editing a file
+    p			    for |:write|: creates the file's parent directory
 
-{value} cannot contain white space.  It can be any valid value for these
-options.  Examples: >
+{value} cannot contain whitespace.  It can be any valid value for the options.
+Examples: >
 	:e ++ff=unix
 This edits the same file again with 'fileformat' set to "unix". >
 
@@ -452,9 +449,24 @@ This writes the current buffer to "newfile" in latin1 format.
 The message given when writing a file will show "[converted]" when
 'fileencoding' or the value specified with ++enc differs from 'encoding'.
 
-There may be several ++opt arguments, separated by white space.  They must all
+There may be several ++opt arguments, separated by whitespace.  They must all
 appear before any |+cmd| argument.
 
+								*++p*
+The "++p" flag creates the parent directory of the file if it does not exist.
+For example if you edit "foo/bar/file.txt", the ":write ++p" command creates
+"foo/bar/" if necessary before writing the file. >
+
+	:edit foo/bar/file.txt
+	:write ++p
+
+If you want :write (without "++p") to always create missing parent
+directories, add this autocmd to your config: >
+
+	" Auto-create parent directories (except for URIs "://").
+	au BufWritePre,FileWritePre * if @% !~# '\(://\)' | call mkdir(expand('<afile>:p:h'), 'p') | endif
+<
+
 								*++bad*
 The argument of "++bad=" specifies what happens with characters that can't be
 converted and illegal bytes.  It can be one of three things:
@@ -895,11 +907,13 @@ Note: When the 'write' option is off, you are not able to write any file.
 					*E502* *E503* *E504* *E505*
 					*E512* *E514* *E667* *E949*
 :w[rite] [++opt]	Write the whole buffer to the current file.  This is
-			the normal way to save changes to a file.  It fails
-			when the 'readonly' option is set or when there is
-			another reason why the file can't be written.
-			For ++opt see |++opt|, but only ++bin, ++nobin, ++ff
-			and ++enc are effective.
+			the normal way to save changes to a file.  Fails when
+			'readonly' is set or when there is another reason why
+			the file can't be written, such as when the parent
+			directory doesn't exist (use |++p| to avoid that).
+			For ++opt see |++opt|, but only ++p, ++bin, ++nobin,
+			++ff and ++enc are effective.
+
 
 :w[rite]! [++opt]	Like ":write", but forcefully write when 'readonly' is
 			set or there is another reason why writing was
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index c989b67b96..61d540a3dd 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1708,13 +1708,13 @@ v:charconvert_to
 
 					*v:cmdarg* *cmdarg-variable*
 v:cmdarg	This variable is used for two purposes:
-		1. The extra arguments given to a file read/write command.
-		   Currently these are "++enc=" and "++ff=".  This variable is
-		   set before an autocommand event for a file read/write
-		   command is triggered.  There is a leading space to make it
-		   possible to append this variable directly after the
-		   read/write command.  Note: The "+cmd" argument isn't
-		   included here, because it will be executed anyway.
+		1. The extra arguments ("++p", "++enc=", "++ff=") given to
+		   a file read/write command.  This is set before an
+		   autocommand event for a file read/write command is
+		   triggered.  There is a leading space to make it possible to
+		   append this variable directly after the read/write command.
+		   Note: "+cmd" isn't included here, because it will be
+		   executed anyway.
 		2. When printing a PostScript file with ":hardcopy" this is
 		   the argument for the ":hardcopy" command.  This can be used
 		   in 'printexpr'.
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 37a0a8c076..89a6e89511 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -325,7 +325,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
       },
     }
 <
-  or if using 'nvim-lspconfig', you can use the {handlers} key of `setup()`:
+  or if using "nvim-lspconfig", you can use the {handlers} key of `setup()`:
   >lua
 
     require('lspconfig').rust_analyzer.setup {
@@ -1340,9 +1340,7 @@ start({bufnr}, {client_id}, {opts})          *vim.lsp.semantic_tokens.start()*
     |vim.lsp.buf_attach_client()|. To opt-out of semantic highlighting with a
     server that supports it, you can delete the semanticTokensProvider table
     from the {server_capabilities} of your client in your |LspAttach| callback
-    or your configuration's `on_attach` callback.
-
-    >lua
+    or your configuration's `on_attach` callback. >lua
 
        client.server_capabilities.semanticTokensProvider = nil
 <
diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt
index 4946779a7c..ef407922da 100644
--- a/runtime/doc/nvim.txt
+++ b/runtime/doc/nvim.txt
@@ -24,8 +24,8 @@ Transitioning from Vim                          *nvim-from-vim*
 
 1. To start the transition, create your |init.vim| (user config) file: >vim
 
-    :call mkdir(stdpath('config'), 'p')
     :exe 'edit '.stdpath('config').'/init.vim'
+    :write ++p
 
 2. Add these contents to the file: >vim
 
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 8f2feb416b..5375d971f0 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -176,7 +176,7 @@ a |provider| which transparently uses shell commands to communicate with the
 system clipboard or any other clipboard "backend".
 
 To ALWAYS use the clipboard for ALL operations (instead of interacting with
-the '+' and/or '*' registers explicitly): >vim
+the "+" and/or "*" registers explicitly): >vim
     set clipboard+=unnamedplus
 
 See 'clipboard' for details and options.
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 6a2e74eaf5..5c1725a1f8 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -127,7 +127,7 @@ nvim_cmdwin:
 ==============================================================================
 3. New Features						       *nvim-features*
 
-MAJOR COMPONENTS ~
+MAJOR COMPONENTS
 
 API				|API|
 Job control			|job-control|
@@ -145,7 +145,7 @@ Terminal emulator		|terminal|
 Vimscript parser		|nvim_parse_expression()|
 XDG base directories		|xdg|
 
-USER EXPERIENCE  ~
+USER EXPERIENCE
 
 Working intuitively and consistently is a major goal of Nvim.
 
@@ -176,7 +176,7 @@ Some features are built in that otherwise required external plugins:
 
 - Highlighting the yanked region, see |lua-highlight|.
 
-ARCHITECTURE ~
+ARCHITECTURE
 
 External plugins run in separate processes. |remote-plugin| This improves
 stability and allows those plugins to work without blocking the editor. Even
@@ -187,7 +187,7 @@ Platform and I/O facilities are built upon libuv. Nvim benefits from libuv
 features and bug fixes, and other projects benefit from improvements to libuv
 by Nvim developers.
 
-FEATURES ~
+FEATURES
 
 Command-line highlighting:
   The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted
@@ -206,6 +206,7 @@ Commands:
   |:match| can be invoked before highlight group is defined
   |:source| works with Lua
   User commands can support |:command-preview| to show results as you type
+  |:write| with "++p" flag creates parent directories.
 
 Events:
   |RecordingEnter|
@@ -226,6 +227,7 @@ Functions:
   |stdpath()|
   |system()|, |systemlist()| can run {cmd} directly (without 'shell')
   |matchadd()| can be called before highlight group is defined
+  |writefile()| with "p" flag creates parent directories.
 
 Highlight groups:
   |highlight-blend| controls blend level for a highlight group
@@ -277,7 +279,20 @@ Variables:
   |v:windowid| is always available (for use by external UIs)
 
 ==============================================================================
-4. Changed features					 *nvim-features-changed*
+4. Upstreamed features					 *nvim-upstreamed*
+
+These Nvim features were later integrated into Vim.
+
+- 'fillchars' flags: "eob"
+- 'wildoptions' flags: "pum" enables popupmenu for wildmode completion
+- |<Cmd>|
+- |WinClosed|
+- |WinScrolled|
+- |:sign-define| "numhl" argument
+- |:source| works with anonymous (no file) scripts
+
+==============================================================================
+5. Changed features					 *nvim-features-changed*
 
 Nvim always builds with all features, in contrast to Vim which may have
 certain features removed/added at compile-time. |feature-compile|
@@ -499,7 +514,7 @@ Working directory (Vim implemented some of these later than Nvim):
   working directory. Use `getcwd(-1, -1)` to get the global working directory.
 
 ==============================================================================
-5. Missing legacy features				 *nvim-features-missing*
+6. Missing legacy features				 *nvim-features-missing*
 
 Some legacy Vim features are not yet implemented:
 
@@ -512,7 +527,7 @@ Some legacy Vim features are not yet implemented:
 *:gvim*
 
 ==============================================================================
-6. Removed features					 *nvim-features-removed*
+7. Removed features					 *nvim-features-removed*
 
 These Vim features were intentionally removed from Nvim.
 
diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua
index 83b414bf87..11e62ee793 100644
--- a/runtime/lua/vim/lsp/semantic_tokens.lua
+++ b/runtime/lua/vim/lsp/semantic_tokens.lua
@@ -495,7 +495,6 @@ local M = {}
 --- delete the semanticTokensProvider table from the {server_capabilities} of
 --- your client in your |LspAttach| callback or your configuration's
 --- `on_attach` callback.
----
 --- <pre>lua
 ---   client.server_capabilities.semanticTokensProvider = nil
 --- </pre>
diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 3a0ed5ffc5..78fb917764 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -296,12 +296,11 @@ local function ignore_invalid(s)
   )
 end
 
-local function ignore_parse_error(s, fname)
-  local helpfile = vim.fs.basename(fname)
-  return (helpfile == 'pi_netrw.txt'
+local function ignore_parse_error(s)
+  return (
     -- Ignore parse errors for unclosed tag.
     -- This is common in vimdocs and is treated as plaintext by :help.
-    or s:find("^[`'|*]")
+    s:find("^[`'|*]")
   )
 end
 
@@ -370,7 +369,7 @@ local function visit_validate(root, level, lang_tree, opt, stats)
   end
 
   if node_name == 'ERROR' then
-    if ignore_parse_error(text, opt.fname) then
+    if ignore_parse_error(text) then
       return
     end
     -- Store the raw text to give context to the error report.
@@ -582,7 +581,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
     end
     return s
   elseif node_name == 'ERROR' then
-    if ignore_parse_error(trimmed, opt.fname) then
+    if ignore_parse_error(trimmed) then
       return text
     end
 
diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index db84ecb5d8..ada042e654 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -361,41 +361,20 @@ cleanup:
   return autocmd_list;
 }
 
-/// Create an |autocommand|
+/// Creates an |autocommand| event handler, defined by `callback` (Lua function or Vimscript
+/// function _name_ string) or `command` (Ex command string).
 ///
-/// The API allows for two (mutually exclusive) types of actions to be executed when the autocommand
-/// triggers: a callback function (Lua or Vimscript), or a command (like regular autocommands).
-///
-/// Example using callback:
-/// <pre>lua
-///     -- Lua function
-///     local myluafun = function() print("This buffer enters") end
-///
-///     -- Vimscript function name (as a string)
-///     local myvimfun = "g:MyVimFunction"
-///
-///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-///       pattern = {"*.c", "*.h"},
-///       callback = myluafun,  -- Or myvimfun
-///     })
-/// </pre>
-///
-/// Lua functions receive a table with information about the autocmd event as an argument. To use
-/// a function which itself accepts another (optional) parameter, wrap the function
-/// in a lambda:
+/// Example using Lua callback:
 /// <pre>lua
-///     -- Lua function with an optional parameter.
-///     -- The autocmd callback would pass a table as argument but this
-///     -- function expects number|nil
-///     local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
-///
 ///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
 ///       pattern = {"*.c", "*.h"},
-///       callback = function() myluafun() end,
+///       callback = function(ev)
+///         print(string.format('event fired: %s', vim.inspect(ev)))
+///       end
 ///     })
 /// </pre>
 ///
-/// Example using command:
+/// Example using an Ex command as the handler:
 /// <pre>lua
 ///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
 ///       pattern = {"*.c", "*.h"},
@@ -403,46 +382,28 @@ cleanup:
 ///     })
 /// </pre>
 ///
-/// Example values for pattern:
-/// <pre>lua
-///   pattern = "*.py"
-///   pattern = { "*.py", "*.pyi" }
-/// </pre>
-///
-/// Note: The `pattern` is passed to callbacks and commands as a literal string; environment
-/// variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|.
-/// Instead, |expand()| such variables explicitly:
+/// Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like "$HOME"
+/// and "~" must be expanded explicitly:
 /// <pre>lua
 ///   pattern = vim.fn.expand("~") .. "/some/path/*.py"
 /// </pre>
 ///
-/// Example values for event:
-/// <pre>lua
-///   event = "BufWritePre"
-///   event = {"CursorHold", "BufWritePre", "BufWritePost"}
-/// </pre>
-///
-/// @param event (string|array) The event or events to register this autocommand
-/// @param opts Dictionary of autocommand options:
-///             - group (string|integer) optional: the autocommand group name or
-///             id to match against.
-///             - pattern (string|array) optional: pattern or patterns to match literally
-///             against |autocmd-pattern|.
-///             - buffer (integer) optional: buffer number for buffer local autocommands
+/// @param event (string|array) Event(s) that will trigger the handler (`callback` or `command`).
+/// @param opts Options dict:
+///             - group (string|integer) optional: autocommand group name or id to match against.
+///             - pattern (string|array) optional: pattern(s) to match literally |autocmd-pattern|.
+///             - buffer (integer) optional: buffer number for buffer-local autocommands
 ///             |autocmd-buflocal|. Cannot be used with {pattern}.
-///             - desc (string) optional: description of the autocommand.
-///             - callback (function|string) optional: if a string, the name of a Vimscript function
-///             to call when this autocommand is triggered. Otherwise, a Lua function which is
-///             called when this autocommand is triggered. Cannot be used with {command}. Lua
-///             callbacks can return true to delete the autocommand; in addition, they accept a
-///             single table argument with the following keys:
-///                 - id: (number) the autocommand id
-///                 - event: (string) the name of the event that triggered the autocommand
-///                 |autocmd-events|
-///                 - group: (number|nil) the autocommand group id, if it exists
-///                 - match: (string) the expanded value of |<amatch>|
-///                 - buf: (number) the expanded value of |<abuf>|
-///                 - file: (string) the expanded value of |<afile>|
+///             - desc (string) optional: description (for documentation and troubleshooting).
+///             - callback (function|string) optional: Lua function (or Vimscript function name, if
+///             string) called when the event(s) is triggered. Lua callback can return true to
+///             delete the autocommand, and receives a table argument with these keys:
+///                 - id: (number) autocommand id
+///                 - event: (string) name of the triggered event |autocmd-events|
+///                 - group: (number|nil) autocommand group id, if any
+///                 - match: (string) expanded value of |<amatch>|
+///                 - buf: (number) expanded value of |<abuf>|
+///                 - file: (string) expanded value of |<afile>|
 ///                 - data: (any) arbitrary data passed to |nvim_exec_autocmds()|
 ///             - command (string) optional: Vim command to execute on event. Cannot be used with
 ///             {callback}
@@ -451,7 +412,7 @@ cleanup:
 ///             - nested (boolean) optional: defaults to false. Run nested
 ///             autocommands |autocmd-nested|.
 ///
-/// @return Integer id of the created autocommand.
+/// @return Autocommand id (number)
 /// @see |autocommand|
 /// @see |nvim_del_autocmd()|
 Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autocmd) *opts,
@@ -472,8 +433,7 @@ Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autoc
   }
 
   if (opts->callback.type != kObjectTypeNil && opts->command.type != kObjectTypeNil) {
-    api_set_error(err, kErrorTypeValidation,
-                  "cannot pass both: 'callback' and 'command' for the same autocmd");
+    api_set_error(err, kErrorTypeValidation, "specify either 'callback' or 'command', not both");
     goto cleanup;
   } else if (opts->callback.type != kObjectTypeNil) {
     // TODO(tjdevries): It's possible we could accept callable tables,
diff --git a/test/functional/api/autocmd_spec.lua b/test/functional/api/autocmd_spec.lua
index a923f5df0e..7fb52b097b 100644
--- a/test/functional/api/autocmd_spec.lua
+++ b/test/functional/api/autocmd_spec.lua
@@ -14,14 +14,14 @@ before_each(clear)
 
 describe('autocmd api', function()
   describe('nvim_create_autocmd', function()
-    it('does not allow "command" and "callback" in the same autocmd', function()
-      local ok, _ = pcall(meths.create_autocmd, "BufReadPost", {
+    it('"command" and "callback" are mutually exclusive', function()
+      local rv = pcall_err(meths.create_autocmd, "BufReadPost", {
         pattern = "*.py,*.pyi",
         command = "echo 'Should Have Errored",
-        callback = "not allowed",
+        callback = "NotAllowed",
       })
 
-      eq(false, ok)
+      eq("specify either 'callback' or 'command', not both", rv)
     end)
 
     it('doesnt leak when you use ++once', function()
@@ -60,13 +60,13 @@ describe('autocmd api', function()
     end)
 
     it('does not allow passing buffer and patterns', function()
-      local ok = pcall(meths.create_autocmd, "Filetype", {
+      local rv = pcall_err(meths.create_autocmd, "Filetype", {
         command = "let g:called = g:called + 1",
         buffer = 0,
         pattern = "*.py",
       })
 
-      eq(false, ok)
+      eq("cannot pass both: 'pattern' and 'buffer' for the same autocmd", rv)
     end)
 
     it('does not allow passing invalid buffers', function()