docs(api): improve autocommand docs (#17545)

[skip ci]

1 files changed, 164 insertions, 87 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index fa2f8f974a..13179e9d9e 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3152,129 +3152,206 @@ nvim_tabpage_set_var({tabpage}, {name}, {value})
 Autocmd Functions                                                *api-autocmd*
 
 nvim_create_augroup({name}, {*opts})                   *nvim_create_augroup()*
-                Create or get an augroup.
+                Create or get an autocommand group |autocmd-groups|.
 
-                To get an existing augroup ID, do: >
-                    local id = vim.api.nvim_create_augroup(name, {
+                To get an existing group id, do: >
+                    local id = vim.api.nvim_create_augroup("MyGroup", {
                         clear = false
                     })
 <
 
                 Parameters: ~
-                    {name}  String: The name of the augroup to create
-                    {opts}  Parameters
-                            • clear (bool): Whether to clear existing commands
-                              or not. Defaults to true. See |autocmd-groups|
+                    {name}  String: The name of the group
+                    {opts}  Dictionary Parameters
+                            • clear (bool) optional: defaults to true. Clear
+                              existing commands if the group already exists
+                              |autocmd-groups|.
 
                 Return: ~
-                    opaque value to use with nvim_del_augroup_by_id
+                    Integer id of the created group.
+
+                See also: ~
+                    |autocmd-groups|
 
 nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
-                Create an autocmd.
+                Create an |autocommand|
 
-                Examples:
-                • event: "pat1,pat2,pat3",
-                • event: "pat1"
-                • event: { "pat1" }
-                • event: { "pat1", "pat2", "pat3" }
+                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).
 
-                Parameters: ~
-                    {event}  The event or events to register this autocmd
-                             Required keys: event: string | ArrayOf(string)
+                Example using callback: >
+                    -- Lua function
+                    local myluafun = function() print("This buffer enters") end
 
-                Parameters: ~
-                    {opts}  Optional Parameters:
-                            • callback: (string|function)
-                              • (string): The name of the viml function to
-                                execute when triggering this autocmd
-                              • (function): The lua function to execute when
-                                triggering this autocmd
-                              • NOTE: Cannot be used with {command}
+                    -- Vimscript function name (as a string)
+                    local myvimfun = "g:MyVimFunction"
 
-                            • command: (string) command
-                              • vimscript command
-                              • NOTE: Cannot be used with {callback} Eg.
-                                command = "let g:value_set = v:true"
+                    vim.api.nvim_create_autocmd({
+                      event = {"BufEnter", "BufWinEnter"},
+                      pattern = {"*.c", "*.h"},
+                      callback = myluafun,  -- Or myvimfun
+                    })
+<
+
+                Example using command: >
+                    vim.api.nvim_create_autocmd({
+                      event = {"BufEnter", "BufWinEnter"},
+                      pattern = {"*.c", "*.h"},
+                      command = "echo 'Entering a C or C++ file'",
+                    })
+<
 
-                            • pattern: (string|table)
-                              • pattern or patterns to match against
-                              • defaults to "*".
-                              • NOTE: Cannot be used with {buffer}
+                Example values for pattern: >
+                  pattern = "*.py"
+                  pattern = { "*.py", "*.pyi" }
+<
 
-                            • buffer: (bufnr)
-                              • create a |autocmd-buflocal| autocmd.
-                              • NOTE: Cannot be used with {pattern}
+                Examples values for event: >
+                  event = "BufPreWrite"
+                  event = {"CursorHold", "BufPreWrite", "BufPostWrite"}
+<
 
-                            • group: (string|int) The augroup name or id
-                            • once: (boolean) - See |autocmd-once|
-                            • nested: (boolean) - See |autocmd-nested|
-                            • desc: (string) - Description of the autocmd
+                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 against |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: Lua
+                               function or Vim function (as string) to execute
+                               on event. Cannot be used with {command}
+                             • command (string) optional: Vim command to
+                               execute on event. Cannot be used with
+                               {callback}
+                             • once (boolean) optional: defaults to false. Run
+                               the autocommand only once |autocmd-once|.
+                             • nested (boolean) optional: defaults to false.
+                               Run nested autocommands |autocmd-nested|.
+
+                Return: ~
+                    Integer id of the created autocommand.
 
-                Return: ~
-                    opaque value to use with nvim_del_autocmd
+                See also: ~
+                    |autocommand|
+                    |nvim_del_autocmd()|
 
 nvim_del_augroup_by_id({id})                        *nvim_del_augroup_by_id()*
-                Delete an augroup by {id}. {id} can only be returned when
-                augroup was created with |nvim_create_augroup|.
+                Delete an autocommand group by id.
 
-                NOTE: behavior differs from augroup-delete.
+                To get a group id one can use |nvim_get_autocmds()|.
 
-                When deleting an augroup, autocmds contained by this augroup
-                will also be deleted and cleared. This augroup will no longer
-                exist
+                NOTE: behavior differs from |augroup-delete|. When deleting a
+                group, autocommands contained in this group will also be
+                deleted and cleared. This group will no longer exist.
 
-nvim_del_augroup_by_name({name})                  *nvim_del_augroup_by_name()*
-                Delete an augroup by {name}.
+                Parameters: ~
+                    {id}  Integer The id of the group.
 
-                NOTE: behavior differs from augroup-delete.
+                See also: ~
+                    |nvim_del_augroup_by_name()|
+                    |nvim_create_augroup()|
 
-                When deleting an augroup, autocmds contained by this augroup
-                will also be deleted and cleared. This augroup will no longer
-                exist
+nvim_del_augroup_by_name({name})                  *nvim_del_augroup_by_name()*
+                Delete an autocommand group by name.
 
-nvim_del_autocmd({id})                                    *nvim_del_autocmd()*
-                Delete an autocmd by {id}. Autocmds only return IDs when
-                created via the API. Will not error if called and no autocmds
-                match the {id}.
+                NOTE: behavior differs from |augroup-delete|. When deleting a
+                group, autocommands contained in this group will also be
+                deleted and cleared. This group will no longer exist.
 
                 Parameters: ~
-                    {id}  Integer The ID returned by nvim_create_autocmd
+                    {name}  String The name of the group.
 
-nvim_do_autocmd({event}, {*opts})                          *nvim_do_autocmd()*
-                Do one autocmd.
+                See also: ~
+                    |autocommand-groups|
+
+nvim_del_autocmd({id})                                    *nvim_del_autocmd()*
+                Delete an autocommand by id.
+
+                NOTE: Only autocommands created via the API have an id.
 
                 Parameters: ~
-                    {event}  The event or events to execute
-                    {opts}   Optional Parameters:
-                             • buffer (number) - buffer number
-                               • NOTE: Cannot be used with {pattern}
+                    {id}  Integer The id returned by nvim_create_autocmd
 
-                             • pattern (string|table) - optional, defaults to
-                               "*".
-                               • NOTE: Cannot be used with {buffer}
+                See also: ~
+                    |nvim_create_autocmd()|
 
-                             • group (string|int) - autocmd group name or id
-                             • modeline (boolean) - Default true, see
-                               |<nomodeline>|
+nvim_do_autocmd({event}, {*opts})                          *nvim_do_autocmd()*
+                Execute an autocommand |autocmd-execute|.
+
+                Parameters: ~
+                    {event}  (String|Array) The event or events to execute
+                    {opts}   Dictionary of autocommand options:
+                             • group (string|integer) optional: the
+                               autocommand group name or id to match against.
+                               |autocmd-groups|.
+                             • pattern (string|array) optional: defaults to
+                               "*" |autocmd-pattern|. Cannot be used with
+                               {buffer}.
+                             • buffer (integer) optional: buffer number
+                               |autocmd-buflocal|. Cannot be used with
+                               {pattern}.
+                             • modeline (bool) optional: defaults to true.
+                               Process the modeline after the autocommands
+                               |<nomodeline>|.
 
-nvim_get_autocmds({*opts})                               *nvim_get_autocmds()*
-                Get autocmds that match the requirements passed to {opts}.
+                See also: ~
+                    |:doautocmd|
 
-                Parameters: ~
-                    {opts}  Optional Parameters:
-                            • event : Name or list of name of events to match
-                              against
-                            • group (string|int): Name or id of group to match
-                              against
-                            • pattern: Pattern or list of patterns to match
-                              against. Cannot be used with {buffer}
-                            • buffer: Buffer number or list of buffer numbers
-                              for buffer local autocommands
-                              |autocmd-buflocal|. Cannot be used with
-                              {pattern}
+nvim_get_autocmds({*opts})                               *nvim_get_autocmds()*
+                Get autocommands that match the requirements passed to {opts}.
+
+                These examples will get autocommands matching ALL the given
+                criteria: >
+                  -- Matches all criteria
+                  autocommands = vim.api.nvim_get_autocmds({
+                    group = "MyGroup",
+                    event = {"BufEnter", "BufWinEnter"},
+                    pattern = {"*.c", "*.h"}
+                  })
+
+                  -- All commands from one group
+                  autocommands = vim.api.nvim_get_autocmds({
+                    group = "MyGroup",
+                  })
+<
 
-                Return: ~
-                    A list of autocmds that match
+                NOTE: When multiple patterns or events are provided, it will
+                find all the autocommands that match any combination of them.
+
+                Parameters: ~
+                    {opts}  Dictionary with at least one of the following:
+                            • group (string|integer): the autocommand group
+                              name or id to match against.
+                            • event (string|array): event or events to match
+                              against |autocmd-events|.
+                            • pattern (string|array): pattern or patterns to
+                              match against |autocmd-pattern|.
+
+                Return: ~
+                    Array of autocommands matching the criteria, with each
+                    item containing the following fields:
+                    • id (number): the autocommand id (only when defined with
+                      the API).
+                    • group (integer): the autocommand group id.
+                    • desc (string): the autocommand description.
+                    • event (string): the autocommand event.
+                    • command (string): the autocommand command.
+                    • once (boolean): whether the autocommand is only run
+                      once.
+                    • pattern (string): the autocommand pattern. If the
+                      autocommand is buffer local |autocmd-buffer-local|:
+                    • buflocal (boolean): true if the autocommand is buffer
+                      local.
+                    • buffer (number): the buffer number.
 
 
 ==============================================================================