encoding/gob: document allocation/merge behavior

This is understood, obvious (to me), and well known but has not been clearly documented. Fixes golang#11117. Change-Id: Ib2b1e318924748d1eac0d735ad6286533be7fd39 Reviewed-on: https://go-review.googlesource.com/14693 Reviewed-by: Ian Lance Taylor <[email protected]>
bpd1069 · Sep 17, 2015 · 1216e18 · 1216e18
1 parent cf45271
commit 1216e18
Showing 1 changed file with 6 additions and 0 deletions.
diff --git a/src/encoding/gob/doc.go b/src/encoding/gob/doc.go
@@ -82,6 +82,12 @@ slice has capacity the slice will be extended in place; if not, a new array is
 allocated. Regardless, the length of the resulting slice reports the number of
 elements decoded.
 
+In general, if allocation is required, the decoder will allocate memory. If not,
+it will update the destination variables with values read from the stream. It does
+not initialize them first, so if the destination is a compound value such as a
+map, struct, or slice, the decoded values will be merged elementwise into the
+existing variables.
+
 Functions and channels will not be sent in a gob. Attempting to encode such a value
 at the top level will fail. A struct field of chan or func type is treated exactly
 like an unexported field and is ignored.