From a48a0a4f7b2b1255025ceb128f6cc97fa0f992aa Mon Sep 17 00:00:00 2001
From: Mathias Fußenegger <mfussenegger@users.noreply.github.com>
Date: Wed, 20 Apr 2022 18:42:07 +0200
Subject: 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>
---
 src/nvim/api/autocmd.c | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

(limited to 'src')

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"}, {
-- 
cgit