vim-patch:87410ab3f556 (#27696)

runtime(doc): some improvements to getregion() docs (vim/vim#14122)

- Mention the default selection behavior
- Remove useless sentence
- Correct description about space padding

https://github.com/vim/vim/commit/87410ab3f556121dfb3b30515f40c5f079edd004

3 files changed, 30 insertions, 33 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 290fba5281..a043121adf 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -2928,32 +2928,31 @@ getregion({pos1}, {pos2} [, {opts}])                               *getregion()*
 		The optional argument {opts} is a Dict and supports the
 		following items:
 
-			type		Specify the selection type
+			type		Specify the region's selection type
 					(default: "v"):
 			    "v"		for |charwise| mode
 			    "V"		for |linewise| mode
 			    "<CTRL-V>"	for |blockwise-visual| mode
 
 			exclusive	If |TRUE|, use exclusive selection
-					for the end position 'selection'.
+					for the end position
+					(default: follow 'selection')
 
 		You can get the last selection type by |visualmode()|.
 		If Visual mode is active, use |mode()| to get the Visual mode
 		(e.g., in a |:vmap|).
-		This function uses the line and column number from the
-		specified position.
-		It is useful to get text starting and ending in different
-		columns, such as |charwise-visual| selection.
+		This function is useful to get text starting and ending in
+		different columns, such as a |charwise-visual| selection.
 
 		Note that:
 		- Order of {pos1} and {pos2} doesn't matter, it will always
 		  return content from the upper left position to the lower
 		  right position.
-		- If 'virtualedit' is enabled and selection is past the end of
-		  line, resulting lines are filled with blanks.
-		- If the selection starts or ends in the middle of a multibyte
-		  character, it is not included but its selected part is
-		  substituted with spaces.
+		- If 'virtualedit' is enabled and the region is past the end
+		  of the lines, resulting lines are padded with spaces.
+		- If the region is blockwise and it starts or ends in the
+		  middle of a multi-cell character, it is not included but
+		  its selected part is substituted with spaces.
 		- If {pos1} or {pos2} is not current in the buffer, an empty
 		  list is returned.
 
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index fa13c36a11..ff95edddf6 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3534,32 +3534,31 @@ function vim.fn.getreginfo(regname) end
 --- The optional argument {opts} is a Dict and supports the
 --- following items:
 ---
----   type    Specify the selection type
+---   type    Specify the region's selection type
 ---       (default: "v"):
 ---       "v"    for |charwise| mode
 ---       "V"    for |linewise| mode
 ---       "<CTRL-V>"  for |blockwise-visual| mode
 ---
 ---   exclusive  If |TRUE|, use exclusive selection
----       for the end position 'selection'.
+---       for the end position
+---       (default: follow 'selection')
 ---
 --- You can get the last selection type by |visualmode()|.
 --- If Visual mode is active, use |mode()| to get the Visual mode
 --- (e.g., in a |:vmap|).
---- This function uses the line and column number from the
---- specified position.
---- It is useful to get text starting and ending in different
---- columns, such as |charwise-visual| selection.
+--- This function is useful to get text starting and ending in
+--- different columns, such as a |charwise-visual| selection.
 ---
 --- Note that:
 --- - Order of {pos1} and {pos2} doesn't matter, it will always
 ---   return content from the upper left position to the lower
 ---   right position.
---- - If 'virtualedit' is enabled and selection is past the end of
----   line, resulting lines are filled with blanks.
---- - If the selection starts or ends in the middle of a multibyte
----   character, it is not included but its selected part is
----   substituted with spaces.
+--- - If 'virtualedit' is enabled and the region is past the end
+---   of the lines, resulting lines are padded with spaces.
+--- - If the region is blockwise and it starts or ends in the
+---   middle of a multi-cell character, it is not included but
+---   its selected part is substituted with spaces.
 --- - If {pos1} or {pos2} is not current in the buffer, an empty
 ---   list is returned.
 ---
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index 3f7294bcba..2984ce29c6 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -4368,32 +4368,31 @@ M.funcs = {
       The optional argument {opts} is a Dict and supports the
       following items:
 
-      	type		Specify the selection type
+      	type		Specify the region's selection type
       			(default: "v"):
       	    "v"		for |charwise| mode
       	    "V"		for |linewise| mode
       	    "<CTRL-V>"	for |blockwise-visual| mode
 
       	exclusive	If |TRUE|, use exclusive selection
-      			for the end position 'selection'.
+      			for the end position
+      			(default: follow 'selection')
 
       You can get the last selection type by |visualmode()|.
       If Visual mode is active, use |mode()| to get the Visual mode
       (e.g., in a |:vmap|).
-      This function uses the line and column number from the
-      specified position.
-      It is useful to get text starting and ending in different
-      columns, such as |charwise-visual| selection.
+      This function is useful to get text starting and ending in
+      different columns, such as a |charwise-visual| selection.
 
       Note that:
       - Order of {pos1} and {pos2} doesn't matter, it will always
         return content from the upper left position to the lower
         right position.
-      - If 'virtualedit' is enabled and selection is past the end of
-        line, resulting lines are filled with blanks.
-      - If the selection starts or ends in the middle of a multibyte
-        character, it is not included but its selected part is
-        substituted with spaces.
+      - If 'virtualedit' is enabled and the region is past the end
+        of the lines, resulting lines are padded with spaces.
+      - If the region is blockwise and it starts or ends in the
+        middle of a multi-cell character, it is not included but
+        its selected part is substituted with spaces.
       - If {pos1} or {pos2} is not current in the buffer, an empty
         list is returned.