encoding/gob: document allocation/merge behavior
This is understood, obvious (to me), and well known but has not been clearly documented.
Fixes #11117.
Change-Id: Ib2b1e318924748d1eac0d735ad6286533be7fd39
Reviewed-on: https://go-review.googlesource.com/14693
Reviewed-by: Ian Lance Taylor <iant@golang.org>
diff --git a/src/encoding/gob/doc.go b/src/encoding/gob/doc.go
index 4d3d007..481c757 100644
--- a/src/encoding/gob/doc.go
+++ b/src/encoding/gob/doc.go
@@ -82,6 +82,12 @@
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.
