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

[skip ci]

2 files changed, 293 insertions, 159 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.
 
 
 ==============================================================================
diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index 8a7dd00b2a..94a24705d0 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -36,16 +36,42 @@
 // Used to delete autocmds from nvim_del_autocmd
 static int64_t next_autocmd_id = 1;
 
-/// Get autocmds that match the requirements passed to {opts}.
+/// Get autocommands that match the requirements passed to {opts}.
 ///
-/// @param 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}
+/// These examples will get autocommands matching ALL the given criteria:
+/// <pre>
+///   -- 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",
+///   })
+/// </pre>
 ///
-/// @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.
+///
+/// @param 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.
 Array nvim_get_autocmds(Dict(get_autocmds) *opts, Error *err)
   FUNC_API_SINCE(9)
 {
@@ -301,40 +327,68 @@ cleanup:
   return autocmd_list;
 }
 
-/// Create an 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:
+/// <pre>
+///     -- 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({
+///       event = {"BufEnter", "BufWinEnter"},
+///       pattern = {"*.c", "*.h"},
+///       callback = myluafun,  -- Or myvimfun
+///     })
+/// </pre>
 ///
-/// @param event The event or events to register this autocmd
-///          Required keys:
-///              event: string | ArrayOf(string)
+/// Example using command:
+/// <pre>
+///     vim.api.nvim_create_autocmd({
+///       event = {"BufEnter", "BufWinEnter"},
+///       pattern = {"*.c", "*.h"},
+///       command = "echo 'Entering a C or C++ file'",
+///     })
+/// </pre>
 ///
-///              Examples:
-///                 - event: "pat1,pat2,pat3",
-///                 - event: "pat1"
-///                 - event: { "pat1" }
-///                 - event: { "pat1", "pat2", "pat3" }
+/// Example values for pattern:
+/// <pre>
+///   pattern = "*.py"
+///   pattern = { "*.py", "*.pyi" }
+/// </pre>
 ///
-/// @param 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}
-///         - command: (string) command
-///             - vimscript command
-///             - NOTE: Cannot be used with {callback}
-///                  Eg. command = "let g:value_set = v:true"
-///         - pattern: (string|table)
-///             - pattern or patterns to match against
-///             - defaults to "*".
-///             - NOTE: Cannot be used with {buffer}
-///         - buffer: (bufnr)
-///             - create a |autocmd-buflocal| autocmd.
-///             - NOTE: Cannot be used with {pattern}
-///         - group: (string|int) The augroup name or id
-///         - once: (boolean) - See |autocmd-once|
-///         - nested: (boolean) - See |autocmd-nested|
-///         - desc: (string) - Description of the autocmd
+/// Examples values for event:
+/// <pre>
+///   event = "BufPreWrite"
+///   event = {"CursorHold", "BufPreWrite", "BufPostWrite"}
+/// </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
+///             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|.
 ///
-/// @returns opaque value to use with nvim_del_autocmd
+/// @return Integer id of the created autocommand.
+/// @see |autocommand|
+/// @see |nvim_del_autocmd()|
 Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autocmd) *opts,
                             Error *err)
   FUNC_API_SINCE(9)
@@ -552,33 +606,32 @@ cleanup:
   return autocmd_id;
 }
 
-/// 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}.
+/// Delete an autocommand by id.
 ///
-/// @param id Integer The ID returned by nvim_create_autocmd
+/// NOTE: Only autocommands created via the API have an id.
+/// @param id Integer The id returned by nvim_create_autocmd
+/// @see |nvim_create_autocmd()|
 void nvim_del_autocmd(Integer id)
   FUNC_API_SINCE(9)
 {
   autocmd_delete_id(id);
 }
 
-/// Create or get an augroup.
+/// Create or get an autocommand group |autocmd-groups|.
 ///
-/// To get an existing augroup ID, do:
+/// To get an existing group id, do:
 /// <pre>
-///     local id = vim.api.nvim_create_augroup(name, {
+///     local id = vim.api.nvim_create_augroup("MyGroup", {
 ///         clear = false
 ///     })
 /// </pre>
 ///
-/// @param name String: The name of the augroup to create
-/// @param opts Parameters
-///                 - clear (bool): Whether to clear existing commands or not.
-///                                 Defaults to true.
-///                     See |autocmd-groups|
-///
-/// @returns opaque value to use with nvim_del_augroup_by_id
+/// @param name String: The name of the group
+/// @param opts Dictionary Parameters
+///                 - clear (bool) optional: defaults to true. Clear existing
+///                 commands if the group already exists |autocmd-groups|.
+/// @return Integer id of the created group.
+/// @see |autocmd-groups|
 Integer nvim_create_augroup(uint64_t channel_id, String name, Dict(create_augroup) *opts,
                             Error *err)
   FUNC_API_SINCE(9)
@@ -604,13 +657,15 @@ Integer nvim_create_augroup(uint64_t channel_id, String name, Dict(create_augrou
   return augroup;
 }
 
-/// 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.
+/// @param id Integer The id of the group.
+/// @see |nvim_del_augroup_by_name()|
+/// @see |nvim_create_augroup()|
 void nvim_del_augroup_by_id(Integer id)
   FUNC_API_SINCE(9)
 {
@@ -618,28 +673,30 @@ void nvim_del_augroup_by_id(Integer id)
   augroup_del(name, false);
 }
 
-/// Delete an augroup by {name}.
+/// Delete an autocommand group by name.
 ///
-/// NOTE: behavior differs from augroup-delete.
-///
-/// 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.
+/// @param name String The name of the group.
+/// @see |autocommand-groups|
 void nvim_del_augroup_by_name(String name)
   FUNC_API_SINCE(9)
 {
   augroup_del(name.data, false);
 }
 
-/// Do one autocmd.
-///
-/// @param event The event or events to execute
-/// @param opts Optional Parameters:
-///         - buffer (number) - buffer number
-///             - NOTE: Cannot be used with {pattern}
-///         - pattern (string|table) - optional, defaults to "*".
-///             - NOTE: Cannot be used with {buffer}
-///         - group (string|int) - autocmd group name or id
-///         - modeline (boolean) - Default true, see |<nomodeline>|
+/// Execute an autocommand |autocmd-execute|.
+/// @param event (String|Array) The event or events to execute
+/// @param 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>|.
+/// @see |:doautocmd|
 void nvim_do_autocmd(Object event, Dict(do_autocmd) *opts, Error *err)
   FUNC_API_SINCE(9)
 {