cmd/compile: improve comments, mainly in cmd/compile/internal/types

Add some useful comments, mainly relates to types.Type. (No non-comment
changes.)

Change-Id: I3665ed69b180c4e790af2f9243f65c805083391a
Reviewed-on: https://go-review.googlesource.com/c/go/+/379918
Reviewed-by: Matthew Dempsky <mdempsky@google.com>
Trust: Dan Scales <danscales@google.com>

src/cmd/compile/internal/typecheck/subr.go

@@ -173,6 +173,8 @@ func AddImplicitDots(n *ir.SelectorExpr) *ir.SelectorExpr {
 	return n
 }
 
+// CalcMethods calculates all the methods (including embedding) of a non-interface
+// type t.
 func CalcMethods(t *types.Type) {
 	if t == nil || t.AllMethods().Len() != 0 {
 		return

src/cmd/compile/internal/types/type.go

@@ -75,7 +75,7 @@ const (
 	TNIL
 	TBLANK
 
-	// pseudo-types for frame layout
+	// pseudo-types used temporarily only during frame layout (CalcSize())
 	TFUNCARGS
 	TCHANARGS
 
@@ -136,6 +136,14 @@ var (
 )
 
 // A Type represents a Go type.
+//
+// There may be multiple unnamed types with identical structure. However, there must
+// be a unique Type object for each unique named (defined) type. After noding, a
+// package-level type can be looked up by building its unique symbol sym (sym =
+// package.Lookup(name)) and checking sym.Def. If sym.Def is non-nil, the type
+// already exists at package scope and is available at sym.Def.(*ir.Name).Type().
+// Local types (which may have the same name as a package-level type) are
+// distinguished by the value of vargen.
 type Type struct {
 	// extra contains extra etype-specific fields.
 	// As an optimization, those etype-specific structs which contain exactly
@@ -154,6 +162,7 @@ type Type struct {
 	// TSLICE: Slice
 	// TSSA: string
 	// TTYPEPARAM:  *Typeparam
+	// TUNION: *Union
 	extra interface{}
 
 	// width is the width of this Type in bytes.
@@ -230,7 +239,7 @@ func (t *Type) SetRecur(b bool)      { t.flags.set(typeRecur, b) }
 // Generic types should never have alg functions.
 func (t *Type) SetHasTParam(b bool) { t.flags.set(typeHasTParam, b); t.flags.set(typeNoalg, b) }
 
-// Should always do SetHasShape(true) when doing SeIsShape(true).
+// Should always do SetHasShape(true) when doing SetIsShape(true).
 func (t *Type) SetIsShape(b bool)  { t.flags.set(typeIsShape, b) }
 func (t *Type) SetHasShape(b bool) { t.flags.set(typeHasShape, b) }
 
@@ -494,13 +503,17 @@ type Field struct {
 
 	Embedded uint8 // embedded field
 
-	Pos  src.XPos
+	Pos src.XPos
+
+	// Name of field/method/parameter. Can be nil for interface fields embedded
+	// in interfaces and unnamed parameters.
 	Sym  *Sym
 	Type *Type  // field type
 	Note string // literal string annotation
 
-	// For fields that represent function parameters, Nname points
-	// to the associated ONAME Node.
+	// For fields that represent function parameters, Nname points to the
+	// associated ONAME Node. For fields that represent methods, Nname points to
+	// the function name node.
 	Nname Object
 
 	// Offset in bytes of this field or method within its enclosing struct
@@ -1018,7 +1031,9 @@ func (t *Type) Methods() *Fields {
 }
 
 // AllMethods returns a pointer to all the methods (including embedding) for type t.
-// For an interface type, this is the set of methods that are typically iterated over.
+// For an interface type, this is the set of methods that are typically iterated
+// over. For non-interface types, AllMethods() only returns a valid result after
+// CalcMethods() has been called at least once.
 func (t *Type) AllMethods() *Fields {
 	if t.kind == TINTER {
 		// Calculate the full method set of an interface type on the fly
@@ -1749,8 +1764,9 @@ func (t *Type) SetVargen() {
 	t.vargen = typeGen
 }
 
-// SetUnderlying sets the underlying type. SetUnderlying automatically updates any
-// types that were waiting for this type to be completed.
+// SetUnderlying sets the underlying type of an incomplete type (i.e. type whose kind
+// is currently TFORW). SetUnderlying automatically updates any types that were waiting
+// for this type to be completed.
 func (t *Type) SetUnderlying(underlying *Type) {
 	if underlying.kind == TFORW {
 		// This type isn't computed yet; when it is, update n.
@@ -2210,4 +2226,5 @@ var (
 
 var SimType [NTYPE]Kind
 
+// Fake package for shape types (see typecheck.Shapify()).
 var ShapePkg = NewPkg("go.shape", "go.shape")