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.

5 files changed, 24 insertions, 17 deletions

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|
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 9891926632..757cfecb46 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -122,6 +122,9 @@ The following changes may require adaptations in user config or plugins.
 
 • |shm-q| now fully hides macro recording message instead of only shortening it.
 
+• Returning any truthy value from a callback passed to |nvim_create_autocmd()|
+  (rather than just `true`) will delete the autocommand.
+
 ==============================================================================
 BREAKING CHANGES IN HEAD                                    *news-breaking-dev*
 
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`
diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index 4f67f682f1..90b7f3a5c6 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -378,8 +378,9 @@ cleanup:
 ///             |autocmd-buflocal|. Cannot be used with {pattern}.
 ///             - desc (string) optional: description (for documentation and 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:
+///             string) called when the 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|
 ///                 - group: (number|nil) autocommand group id, if any
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 110154f8de..257e5e6b05 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -112,7 +112,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
 ///        Not for Lua callbacks.
 /// @param  opts  Optional parameters.
 ///             - on_lines: Lua callback invoked on change.
-///               Return `true` to detach. Args:
+///               Return a truthy value (not `false` or `nil`) to detach. Args:
 ///               - the string "lines"
 ///               - buffer handle
 ///               - b:changedtick
@@ -125,8 +125,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
 ///             - on_bytes: Lua callback invoked on change.
 ///               This callback receives more granular information about the
 ///               change compared to on_lines.
-///               Return `true` to detach.
-///               Args:
+///               Return a truthy value (not `false` or `nil`) to detach. Args:
 ///               - the string "bytes"
 ///               - buffer handle
 ///               - b:changedtick