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 54ad49a721095406e0cc07c05eb0b405aa168504..0aa7c24df9a0343b6fa983ed1efe92bcc4f5a808 100644 (file)
--- a/src/context/context.go
+++ b/src/context/context.go
@@ -443,9 +443,13 @@ func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
 // 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")