go/types: clarify that contexts do not guarantee deduplication

Documentation around the use of types.Context is unclear about whether
contexts guarantee deduplication of identical instances. Add explicit
disclaimers that this is not the case.

Fixes golang#51680

Change-Id: I6651587315d3cbf9e8d70a69d3e2ec5cedd00da5
Reviewed-on: https://go-review.googlesource.com/c/go/+/396536
Trust: Robert Findley <rfindley@google.com>
Run-TryBot: Robert Findley <rfindley@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Robert Griesemer <gri@golang.org>

src/cmd/compile/internal/types2/context.go

@@ -12,11 +12,12 @@ import (
 	"sync"
 )
 
-// An Context is an opaque type checking context. It may be used to share
+// A Context is an opaque type checking context. It may be used to share
 // identical type instances across type-checked packages or calls to
-// Instantiate.
+// Instantiate. Contexts are safe for concurrent use.
 //
-// It is safe for concurrent use.
+// The use of a shared context does not guarantee that identical instances are
+// deduplicated in all cases.
 type Context struct {
 	mu        sync.Mutex
 	typeMap   map[string][]ctxtEntry // type hash -> instances entries

src/cmd/compile/internal/types2/instantiate.go

@@ -24,7 +24,8 @@ import (
 // previous instances with the same identity. As a special case, generic
 // *Signature origin types are only considered identical if they are pointer
 // equivalent, so that instantiating distinct (but possibly identical)
-// signatures will yield different instances.
+// signatures will yield different instances. The use of a shared context does
+// not guarantee that identical instances are deduplicated in all cases.
 //
 // If validate is set, Instantiate verifies that the number of type arguments
 // and parameters match, and that the type arguments satisfy their

src/go/types/context.go

@@ -12,11 +12,12 @@ import (
 	"sync"
 )
 
-// An Context is an opaque type checking context. It may be used to share
+// A Context is an opaque type checking context. It may be used to share
 // identical type instances across type-checked packages or calls to
-// Instantiate.
+// Instantiate. Contexts are safe for concurrent use.
 //
-// It is safe for concurrent use.
+// The use of a shared context does not guarantee that identical instances are
+// deduplicated in all cases.
 type Context struct {
 	mu        sync.Mutex
 	typeMap   map[string][]ctxtEntry // type hash -> instances entries

src/go/types/instantiate.go

@@ -24,7 +24,8 @@ import (
 // previous instances with the same identity. As a special case, generic
 // *Signature origin types are only considered identical if they are pointer
 // equivalent, so that instantiating distinct (but possibly identical)
-// signatures will yield different instances.
+// signatures will yield different instances. The use of a shared context does
+// not guarantee that identical instances are deduplicated in all cases.
 //
 // If validate is set, Instantiate verifies that the number of type arguments
 // and parameters match, and that the type arguments satisfy their