docs(api): specify when decor provider on_buf is called #31634

runtime/doc/api.txt

@@ -2847,8 +2847,8 @@ nvim_set_decoration_provider({ns_id}, {opts})
                  • on_start: called first on each screen redraw >
                     ["start", tick]
 <
-                 • on_buf: called for each buffer being redrawn (before window
+                 • on_buf: called for each buffer being redrawn (once per
-                   callbacks) >
+                   edit, before window callbacks) >
                     ["buf", bufnr, tick]
 <
                  • on_win: called when starting to redraw a specific window. >

runtime/lua/vim/_meta/api.lua

@@ -2134,8 +2134,8 @@ function vim.api.nvim_set_current_win(window) end
 ---   ```
 ---     ["start", tick]
 ---   ```
---- - on_buf: called for each buffer being redrawn (before
+--- - on_buf: called for each buffer being redrawn (once per edit,
----   window callbacks)
+---   before window callbacks)
 ---   ```
 ---     ["buf", bufnr, tick]
 ---   ```

src/nvim/api/extmark.c

@@ -1012,8 +1012,8 @@ void nvim_buf_clear_namespace(Buffer buffer, Integer ns_id, Integer line_start,
 ///               ```
 ///                 ["start", tick]
 ///               ```
-///             - on_buf: called for each buffer being redrawn (before
+///             - on_buf: called for each buffer being redrawn (once per edit,
-///               window callbacks)
+///               before window callbacks)
 ///               ```
 ///                 ["buf", bufnr, tick]
 ///               ```