go/types, types2: add commentary on (non-)guarantees when using contexts

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

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

@@ -12,6 +12,26 @@ import (
 	"sync"
 )
 
+// This file contains a definition of the type-checking context; an opaque type
+// that may be supplied by users during instantiation.
+//
+// Contexts serve two purposes:
+//  - reduce the duplication of identical instances
+//  - short-circuit instantiation cycles
+//
+// For the latter purpose, we must always have a context during instantiation,
+// whether or not it is supplied by the user. For both purposes, it must be the
+// case that hashing a pointer-identical type produces consistent results
+// (somewhat obviously).
+//
+// However, neither of these purposes require that our hash is perfect, and so
+// this was not an explicit design goal of the context type. In fact, due to
+// concurrent use it is convenient not to guarantee de-duplication.
+//
+// Nevertheless, in the future it could be helpful to allow users to leverage
+// contexts to canonicalize instances, and it would probably be possible to
+// achieve such a guarantee.
+
 // 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. Contexts are safe for concurrent use.

src/go/types/context.go

@@ -12,6 +12,26 @@ import (
 	"sync"
 )
 
+// This file contains a definition of the type-checking context; an opaque type
+// that may be supplied by users during instantiation.
+//
+// Contexts serve two purposes:
+//  - reduce the duplication of identical instances
+//  - short-circuit instantiation cycles
+//
+// For the latter purpose, we must always have a context during instantiation,
+// whether or not it is supplied by the user. For both purposes, it must be the
+// case that hashing a pointer-identical type produces consistent results
+// (somewhat obviously).
+//
+// However, neither of these purposes require that our hash is perfect, and so
+// this was not an explicit design goal of the context type. In fact, due to
+// concurrent use it is convenient not to guarantee de-duplication.
+//
+// Nevertheless, in the future it could be helpful to allow users to leverage
+// contexts to canonicalize instances, and it would probably be possible to
+// achieve such a guarantee.
+
 // 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. Contexts are safe for concurrent use.