docs(api): add example showing necessity to wrap callback function (#18179)

Some people ran into issues trying to use `callback = myluafun` because
of the event data payload.


Co-authored-by: Gregory Anders <8965202+gpanders@users.noreply.github.com>

1 files changed, 16 insertions, 0 deletions

diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index a012f3d7fc..45972ec8ea 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -346,6 +346,22 @@ cleanup:
 ///     })
 /// </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:
+///
+/// <pre>
+///     -- 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,
+///     })
+/// </pre>
+///
 /// Example using command:
 /// <pre>
 ///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {