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>

diff --git a/src/cmd/compile/internal/typecheck/subr.go b/src/cmd/compile/internal/typecheck/subr.go
index 9f6966233d5d4dc4d6296cb04133a1c53a241382..ac90d87f2617eb317624d0e5d46922fe0ded4195 100644 (file)
--- a/src/cmd/compile/internal/typecheck/subr.go
+++ b/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

diff --git a/src/cmd/compile/internal/types/type.go b/src/cmd/compile/internal/types/type.go
index 7d22e2da234e6fd8b3d075ff956fe198888cb22e..fe352e0b6e03ebb1d904b54414f498d0feeb8dbe 100644 (file)
--- a/src/cmd/compile/internal/types/type.go
+++ b/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")