From 55a4aa41bb27aa9439fea11c4ebcfec2ee87844d Mon Sep 17 00:00:00 2001
From: Gregory Anders <8965202+gpanders@users.noreply.github.com>
Date: Thu, 15 Feb 2024 19:56:58 -0600
Subject: docs: document breaking change for nvim_create_autocmd callback
 (#27484)

https://github.com/neovim/neovim/pull/27428 changed the semantics of
callbacks passed to nvim_create_autocmd such that any truthy value will
delete the autocommand (rather than just the literal boolean value
`true`). Update the documentation accordingly and add an entry to
`news.txt`.

The behavior is now consistent between nvim_create_autocmd and
nvim_buf_attach.
---
 runtime/lua/vim/_meta/api.lua | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

(limited to 'runtime/lua/vim/_meta/api.lua')

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index f46ab8023f..0978f0acf5 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -155,8 +155,9 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
 ---                    will be `nvim_buf_changedtick_event`. Not for Lua
 ---                    callbacks.
 --- @param opts vim.api.keyset.buf_attach Optional parameters.
----                    • on_lines: Lua callback invoked on change. Return `true` to
----                      detach. Args:
+---                    • on_lines: Lua callback invoked on change. Return a
+---                      truthy value (not `false` or `nil`)
+---                      to detach. Args:
 ---                      • the string "lines"
 ---                      • buffer handle
 ---                      • b:changedtick
@@ -169,7 +170,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
 ---
 ---                    • on_bytes: Lua callback invoked on change. This
 ---                      callback receives more granular information about the
----                      change compared to on_lines. Return `true` to
+---                      change compared to on_lines. Return a truthy value
+---                      (not `false` or `nil`) to
 ---                      detach. Args:
 ---                      • the string "bytes"
 ---                      • buffer handle
@@ -863,9 +865,9 @@ function vim.api.nvim_create_augroup(name, opts) end
 ---                troubleshooting).
 ---              • callback (function|string) optional: Lua function (or
 ---                Vimscript function name, if string) called when the
----                event(s) is triggered. Lua callback can return true to
----                delete the autocommand, and receives a table argument with
----                these keys:
+---                event(s) is triggered. Lua callback can return a truthy
+---                value (not `false` or `nil`) to delete the
+---                autocommand. Receives a table argument with these keys:
 ---                • id: (number) autocommand id
 ---                • event: (string) name of the triggered event
 ---                  `autocmd-events`
-- 
cgit