[dev.typeparams] cmd/compile: rename types.Type.{Short,Long}String to {Link,Name}String

The original names "ShortString" and "LongString" refer back to the
fmt verbs used to request their formatting styles. However, I always
get confused working with them, in particular because (1) the
"ShortString" description, which uses package-path qualification, is
actually generally longer than the "LongString" description, which
uses package-name qualification; and (2) the documentation mentions
how they're often used, but doesn't actually describe why they're safe
for those purposes.

This CL renames them to "LinkString" and "NameString", respectively,
based on their primary use cases. It also attempts to more completely
describe the strings they return and how they can be used correctly.

Change-Id: I9158ae3eafa8ac53da31a78c7a6d929dc0199afe
Reviewed-on: https://go-review.googlesource.com/c/go/+/330910
Trust: Matthew Dempsky <mdempsky@google.com>
Run-TryBot: Matthew Dempsky <mdempsky@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Robert Griesemer <gri@golang.org>

1 files changed, 29 insertions, 9 deletions

diff --git a/src/cmd/compile/internal/types/fmt.go b/src/cmd/compile/internal/types/fmt.go
index b4d1f6c8bbd..095b795d036 100644
--- a/src/cmd/compile/internal/types/fmt.go
+++ b/src/cmd/compile/internal/types/fmt.go
@@ -242,17 +242,37 @@ func (t *Type) String() string {
 	return tconv(t, 0, fmtGo)
 }
 
-// ShortString generates a short description of t.
-// It is used in autogenerated method names, reflection,
-// and itab names.
-func (t *Type) ShortString() string {
+// LinkString returns an unexpanded string description of t, suitable
+// for use in link symbols. "Unexpanded" here means that the
+// description uses `"".` to qualify identifiers from the current
+// package, and "expansion" refers to the renaming step performed by
+// the linker to replace these qualifiers with proper `path/to/pkg.`
+// qualifiers.
+//
+// After expansion, the description corresponds to type identity. That
+// is, for any pair of types t1 and t2, Identical(t1, t2) and
+// expand(t1.LinkString()) == expand(t2.LinkString()) report the same
+// value.
+//
+// Within a single compilation unit, LinkString always returns the
+// same unexpanded description for identical types. Thus it's safe to
+// use as a map key to implement a type-identity-keyed map. However,
+// make sure all LinkString calls used for this purpose happen within
+// the same compile process; the string keys are not stable across
+// multiple processes.
+func (t *Type) LinkString() string {
 	return tconv(t, 0, fmtTypeID)
 }
 
-// LongString generates a complete description of t.
-// It is useful for reflection,
-// or when a unique fingerprint or hash of a type is required.
-func (t *Type) LongString() string {
+// NameString generates a user-readable, mostly unique string
+// description of t. NameString always returns the same description
+// for identical types, even across compilation units.
+//
+// NameString qualifies identifiers by package name, so it has
+// collisions when different packages share the same names and
+// identifiers. It also does not distinguish function-scope defined
+// types from package-scoped defined types or from each other.
+func (t *Type) NameString() string {
 	return tconv(t, 0, fmtTypeIDName)
 }
 
@@ -677,7 +697,7 @@ func FmtConst(v constant.Value, sharp bool) string {
 
 // TypeHash computes a hash value for type t to use in type switch statements.
 func TypeHash(t *Type) uint32 {
-	p := t.LongString()
+	p := t.NameString()
 
 	// Using MD5 is overkill, but reduces accidental collisions.
 	h := md5.Sum([]byte(p))