runtime(doc): further improve docs about List/Blob += operator

closes: #13990

Signed-off-by: zeertzjq <zeertzjq@outlook.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

2 files changed, 30 insertions, 10 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 3dbbbeafb2..e3a9f20136 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1,4 +1,4 @@
-*eval.txt*	For Vim version 9.1.  Last change: 2024 Feb 07
+*eval.txt*	For Vim version 9.1.  Last change: 2024 Feb 08
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -303,12 +303,15 @@ List concatenation ~
 							*list-concatenation*
 Two lists can be concatenated with the "+" operator: >
 	:let longlist = mylist + [5, 6]
-A list can be concatenated with another one in place using the "+=" operator or |extend()|: >
+	:let longlist = [5, 6] + mylist
+To prepend or append an item, turn it into a list by putting [] around it.
+
+A list can be concatenated with another one in-place using |:let+=| or
+|extend()|: >
 	:let mylist += [7, 8]
 	:call extend(mylist, [7, 8])
-
-To prepend or append an item, turn the item into a list by putting [] around
-it.  To change a list in-place, refer to |list-modification| below.
+<
+See |list-modification| below for more about changing a list in-place.
 
 
 Sublist ~
@@ -427,8 +430,7 @@ To change part of a list you can specify the first and last item to be
 modified.  The value must at least have the number of items in the range: >
 	:let list[3:5] = [3, 4, 5]
 
-To add items to a List in-place, you can use the += operator
-|list-concatenation|: >
+To add items to a List in-place, you can use |:let+=| (|list-concatenation|): >
 	:let listA = [1, 2]
 	:let listA += [3, 4]
 <
@@ -760,12 +762,15 @@ This calls Doit() with 0x11, 0x22 and 0x33.
 
 
 Blob concatenation ~
-
+							*blob-concatenation*
 Two blobs can be concatenated with the "+" operator: >
 	:let longblob = myblob + 0z4455
+	:let longblob = 0z4455 + myblob
+<
+A blob can be concatenated with another one in-place using |:let+=|: >
 	:let myblob += 0z6677
-
-To change a blob in-place see |blob-modification| below.
+<
+See |blob-modification| below for more about changing a blob in-place.
 
 
 Part of a blob ~
@@ -808,6 +813,18 @@ To change part of a blob you can specify the first and last byte to be
 modified.  The value must have the same number of bytes in the range: >
 	:let blob[3:5] = 0z334455
 
+To add items to a Blob in-place, you can use |:let+=| (|blob-concatenation|): >
+	:let blobA = 0z1122
+	:let blobA += 0z3344
+<
+When two variables refer to the same Blob, changing one Blob in-place will
+cause the referenced Blob to be changed in-place: >
+	:let blobA = 0z1122
+	:let blobB = blobA
+	:let blobB += 0z3344
+	:echo blobA
+	0z11223344
+<
 You can also use the functions |add()|, |remove()| and |insert()|.
 
 
@@ -2824,6 +2841,8 @@ declarations and assignments do not use a command.  |vim9-declaration|
 :let {var} ..= {expr1}	Like ":let {var} = {var} .. {expr1}".
 			These fail if {var} was not set yet and when the type
 			of {var} and {expr1} don't fit the operator.
+			`+=` modifies a |List| or a |Blob| in-place instead of
+			creating a new one.
 			`.=` is not supported with Vim script version 2 and
 			later, see |vimscript-version|.
 
diff --git a/runtime/doc/tags b/runtime/doc/tags
index ebde436485..d5ccb99da0 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -6124,6 +6124,7 @@ binary-number	eval.txt	/*binary-number*
 bitwise-function	usr_41.txt	/*bitwise-function*
 bitwise-shift	eval.txt	/*bitwise-shift*
 blob	eval.txt	/*blob*
+blob-concatenation	eval.txt	/*blob-concatenation*
 blob-functions	usr_41.txt	/*blob-functions*
 blob-identity	eval.txt	/*blob-identity*
 blob-index	eval.txt	/*blob-index*