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

1 files changed, 31 insertions, 66 deletions

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|