internal/gcimporter: document non-idempotence of export∘import

In gopls we were recently surprised to discover that the
the message obtained by exporting a types.Package, and the
message obtained by importing and reexporting that message,
differ.

(Specifically because the importer calls NewInterfaceType,
which has a shortcut for empty interfaces, and this shortcut
is not used by go/types, so the importer produces a more
compact data structure than go/types. There may be other examples.)

This change documents the longstanding invariant that the encoding
is deterministic for a given types.Package data structure, while
also explicitly disclaiming that the composition of export∘import
is idemptotent.

Change-Id: Ie07efc1046315cd2104e78714d8312ecdf10e817
Reviewed-on: https://go-review.googlesource.com/c/tools/+/472075
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Robert Findley <rfindley@google.com>
Run-TryBot: Alan Donovan <adonovan@google.com>
Reviewed-by: Matthew Dempsky <mdempsky@google.com>
gopls-CI: kokoro <noreply+kokoro@google.com>

internal/gcimporter/gcimporter.go

@@ -7,6 +7,18 @@
 // Package gcimporter provides various functions for reading
 // gc-generated object files that can be used to implement the
 // Importer interface defined by the Go 1.5 standard library package.
+//
+// The encoding is deterministic: if the encoder is applied twice to
+// the same types.Package data structure, both encodings are equal.
+// This property may be important to avoid spurious changes in
+// applications such as build systems.
+//
+// However, the encoder is not necessarily idempotent. Importing an
+// exported package may yield a types.Package that, while it
+// represents the same set of Go types as the original, may differ in
+// the details of its internal representation. Because of these
+// differences, re-encoding the imported package may yield a
+// different, but equally valid, encoding of the package.
 package gcimporter // import "golang.org/x/tools/internal/gcimporter"
 
 import (