context: document appropriate WithValue key type more
Fixes #17826
Updates #17302
Change-Id: I7c1ebd965e679e7169a97e62d27ae3ede2473aa1
Reviewed-on: https://go-review.googlesource.com/33152
Reviewed-by: Ian Lance Taylor <iant@golang.org>
diff --git a/src/context/context.go b/src/context/context.go
index 54ad49a..0aa7c24 100644
--- a/src/context/context.go
+++ b/src/context/context.go
@@ -443,9 +443,13 @@
// Use context Values only for request-scoped data that transits processes and
// APIs, not for passing optional parameters to functions.
//
-// The provided key must be comparable and should not be
-// of type string or any other built-in type.
-// Users of WithValue should define their own types for keys.
+// The provided key must be comparable and should not be of type
+// string or any other built-in type to avoid collisions between
+// packages using context. Users of WithValue should define their own
+// types for keys. To avoid allocating when assigning to an
+// interface{}, context keys often have concrete type
+// struct{}. Alternatively, exported context key variables' static
+// type should be a pointer or interface.
func WithValue(parent Context, key, val interface{}) Context {
if key == nil {
panic("nil key")
