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>

2 files changed, 32 insertions, 0 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 9e0002db48..5b045f80ff 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3221,6 +3221,22 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
                     })
 <
 
+                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 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: >
                     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
                       pattern = {"*.c", "*.h"},
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"}, {