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/doc/api.txt | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

(limited to 'runtime/doc/api.txt')

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 85b3dffb4b..83b50dcdbe 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -2099,8 +2099,9 @@ nvim_buf_attach({buffer}, {send_buffer}, {*opts})          *nvim_buf_attach()*
                        will be `nvim_buf_changedtick_event`. Not for Lua
                        callbacks.
       • {opts}         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
@@ -2113,7 +2114,8 @@ nvim_buf_attach({buffer}, {send_buffer}, {*opts})          *nvim_buf_attach()*
 
                        • 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
@@ -3457,9 +3459,9 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
                    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