docs: more details about vim.region (#21116)

1 files changed, 6 insertions, 3 deletions

diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index f2875e5646..fd6a5865ce 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -397,14 +397,17 @@ do
   vim.t = make_dict_accessor('t')
 end
 
---- Get a table of lines with start, end columns for a region marked by two points
+--- Get a table of lines with start, end columns for a region marked by two points.
+--- Input and output positions are (0,0)-indexed and indicate byte positions.
 ---
 ---@param bufnr integer number of buffer
 ---@param pos1 integer[] (line, column) tuple marking beginning of region
 ---@param pos2 integer[] (line, column) tuple marking end of region
 ---@param regtype string type of selection, see |setreg()|
----@param inclusive boolean indicating whether the selection is end-inclusive
----@return table region Table of the form `{linenr = {startcol,endcol}}`
+---@param inclusive boolean indicating whether column of pos2 is inclusive
+---@return table region Table of the form `{linenr = {startcol,endcol}}`.
+---        `endcol` is exclusive, and whole lines are marked with
+---        `{startcol,endcol} = {0,-1}`.
 function vim.region(bufnr, pos1, pos2, regtype, inclusive)
   if not vim.api.nvim_buf_is_loaded(bufnr) then
     vim.fn.bufload(bufnr)