docs: add docs for on_range()

runtime/doc/api.txt

@@ -2825,11 +2825,12 @@ nvim_set_decoration_provider({ns_id}, {opts})
     Note: this function should not be called often. Rather, the callbacks
     themselves can be used to throttle unneeded callbacks. the `on_start`
     callback can return `false` to disable the provider until the next redraw.
-    Similarly, return `false` in `on_win` will skip the `on_line` calls for
+    Similarly, return `false` in `on_win` will skip the `on_line` and
-    that window (but any extmarks set in `on_win` will still be used). A
+    `on_range` calls for that window (but any extmarks set in `on_win` will
-    plugin managing multiple sources of decoration should ideally only set one
+    still be used). A plugin managing multiple sources of decoration should
-    provider, and merge the sources internally. You can use multiple `ns_id`
+    ideally only set one provider, and merge the sources internally. You can
-    for the extmarks set/modified inside the callback anyway.
+    use multiple `ns_id` for the extmarks set/modified inside the callback
+    anyway.
 
     Note: doing anything other than setting extmarks is considered
     experimental. Doing things like changing options are not explicitly
@@ -2837,8 +2838,8 @@ nvim_set_decoration_provider({ns_id}, {opts})
     consumption). Doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is
     quite dubious for the moment.
 
-    Note: It is not allowed to remove or update extmarks in `on_line`
+    Note: It is not allowed to remove or update extmarks in `on_line` and
-    callbacks.
+    `on_range` callbacks.
 
     Attributes: ~
         Lua |vim.api| only
@@ -2859,6 +2860,14 @@ nvim_set_decoration_provider({ns_id}, {opts})
                  • on_line: called for each buffer line being redrawn. (The
                    interaction with fold lines is subject to change) >
                     ["line", winid, bufnr, row]
+<
+                 • on_range: called for each buffer range being redrawn. Range
+                   is end-exclusive and may span multiple lines. Range bounds
+                   point to the first byte of a character. An end position of
+                   the form (lnum, 0), including (number of lines, 0), is
+                   valid and indicates that EOL of the preceding line is
+                   included. >
+                    ["range", winid, bufnr, begin_row, begin_col, end_row, end_col]
 <
                  • on_end: called at the end of a redraw cycle >
                     ["end", tick]

runtime/doc/news.txt

@@ -172,6 +172,7 @@ API
 
 • |nvim__ns_set()| can set properties for a namespace
 • |vim.json.encode()| has an option to enable forward slash escaping
+• Decoration provider has `on_range()` callback.
 
 DEFAULTS
 

runtime/lua/vim/_meta/api.lua

@@ -2116,8 +2116,8 @@ function vim.api.nvim_set_current_win(window) end
 --- Note: this function should not be called often. Rather, the callbacks
 --- themselves can be used to throttle unneeded callbacks. the `on_start`
 --- callback can return `false` to disable the provider until the next redraw.
---- Similarly, return `false` in `on_win` will skip the `on_line` calls
+--- Similarly, return `false` in `on_win` will skip the `on_line` and `on_range`
---- for that window (but any extmarks set in `on_win` will still be used).
+--- calls for that window (but any extmarks set in `on_win` will still be used).
 --- A plugin managing multiple sources of decoration should ideally only set
 --- one provider, and merge the sources internally. You can use multiple `ns_id`
 --- for the extmarks set/modified inside the callback anyway.
@@ -2128,7 +2128,8 @@ function vim.api.nvim_set_current_win(window) end
 --- Doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is quite dubious
 --- for the moment.
 ---
---- Note: It is not allowed to remove or update extmarks in `on_line` callbacks.
+--- Note: It is not allowed to remove or update extmarks
+--- in `on_line` and `on_range` callbacks.
 ---
 --- @param ns_id integer Namespace id from `nvim_create_namespace()`
 --- @param opts vim.api.keyset.set_decoration_provider Table of callbacks:
@@ -2150,6 +2151,14 @@ function vim.api.nvim_set_current_win(window) end
 ---   ```
 ---     ["line", winid, bufnr, row]
 ---   ```
+--- - on_range: called for each buffer range being redrawn.
+---   Range is end-exclusive and may span multiple lines. Range
+---   bounds point to the first byte of a character. An end position
+---   of the form (lnum, 0), including (number of lines, 0), is valid
+---   and indicates that EOL of the preceding line is included.
+---   ```
+---     ["range", winid, bufnr, begin_row, begin_col, end_row, end_col]
+---   ```
 --- - on_end: called at the end of a redraw cycle
 ---   ```
 ---     ["end", tick]

src/nvim/api/extmark.c

@@ -992,8 +992,8 @@ void nvim_buf_clear_namespace(Buffer buffer, Integer ns_id, Integer line_start,
 /// Note: this function should not be called often. Rather, the callbacks
 /// themselves can be used to throttle unneeded callbacks. the `on_start`
 /// callback can return `false` to disable the provider until the next redraw.
-/// Similarly, return `false` in `on_win` will skip the `on_line` calls
+/// Similarly, return `false` in `on_win` will skip the `on_line` and `on_range`
-/// for that window (but any extmarks set in `on_win` will still be used).
+/// calls for that window (but any extmarks set in `on_win` will still be used).
 /// A plugin managing multiple sources of decoration should ideally only set
 /// one provider, and merge the sources internally. You can use multiple `ns_id`
 /// for the extmarks set/modified inside the callback anyway.
@@ -1004,7 +1004,8 @@ void nvim_buf_clear_namespace(Buffer buffer, Integer ns_id, Integer line_start,
 /// Doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is quite dubious
 /// for the moment.
 ///
-/// Note: It is not allowed to remove or update extmarks in `on_line` callbacks.
+/// Note: It is not allowed to remove or update extmarks
+/// in `on_line` and `on_range` callbacks.
 ///
 /// @param ns_id  Namespace id from |nvim_create_namespace()|
 /// @param opts  Table of callbacks:
@@ -1026,6 +1027,14 @@ void nvim_buf_clear_namespace(Buffer buffer, Integer ns_id, Integer line_start,
 ///               ```
 ///                 ["line", winid, bufnr, row]
 ///               ```
+///             - on_range: called for each buffer range being redrawn.
+///               Range is end-exclusive and may span multiple lines. Range
+///               bounds point to the first byte of a character. An end position
+///               of the form (lnum, 0), including (number of lines, 0), is valid
+///               and indicates that EOL of the preceding line is included.
+///               ```
+///                 ["range", winid, bufnr, begin_row, begin_col, end_row, end_col]
+///               ```
 ///             - on_end: called at the end of a redraw cycle
 ///               ```
 ///                 ["end", tick]