go/types, types2: clarify documentation with respect to generic types

Address several areas where documentation was inaccurate or unclear
regarding generic types. Also prefer the use of the word 'generic' over
'parameterized', and add additional documentation for the use of
SetConstraint.

For #49593

Change-Id: Iccac60d1b3e2c45a57a3d03b3c10984293af57dd
Reviewed-on: https://go-review.googlesource.com/c/go/+/391154
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>

diff --git a/src/cmd/compile/internal/types2/api.go b/src/cmd/compile/internal/types2/api.go
index 584f613a64282cccefe29ac68618f7c7c4e73060..d864c96fb612ace875b9d4291fd4e5cadcb7a3f2 100644 (file)
--- a/src/cmd/compile/internal/types2/api.go
+++ b/src/cmd/compile/internal/types2/api.go
@@ -204,12 +204,12 @@ type Info struct {
        // qualified identifiers are collected in the Uses map.
        Types map[syntax.Expr]TypeAndValue
 
-       // Instances maps identifiers denoting parameterized types or functions to
-       // their type arguments and instantiated type.
+       // Instances maps identifiers denoting generic types or functions to their
+       // type arguments and instantiated type.
        //
        // For example, Instances will map the identifier for 'T' in the type
        // instantiation T[int, string] to the type arguments [int, string] and
-       // resulting instantiated *Named type. Given a parameterized function
+       // resulting instantiated *Named type. Given a generic function
        // func F[A any](A), Instances will map the identifier for 'F' in the call
        // expression F(int(1)) to the inferred type arguments [int], and resulting
        // instantiated *Signature.

diff --git a/src/cmd/compile/internal/types2/instantiate.go b/src/cmd/compile/internal/types2/instantiate.go
index c2653a383443269b96a66651da8b8204ccfd34e7..9eced489dcf114a190838f93258faa1c7a8cd707 100644 (file)
--- a/src/cmd/compile/internal/types2/instantiate.go
+++ b/src/cmd/compile/internal/types2/instantiate.go
@@ -15,10 +15,10 @@ import (
 
 // Instantiate instantiates the type orig with the given type arguments targs.
 // orig must be a *Named or a *Signature type. If there is no error, the
-// resulting Type is a new, instantiated (not parameterized) type of the same
-// kind (either a *Named or a *Signature). Methods attached to a *Named type
-// are also instantiated, and associated with a new *Func that has the same
-// position as the original method, but nil function scope.
+// resulting Type is an instantiated type of the same kind (either a *Named or
+// a *Signature). Methods attached to a *Named type are also instantiated, and
+// associated with a new *Func that has the same position as the original
+// method, but nil function scope.
 //
 // If ctxt is non-nil, it may be used to de-duplicate the instance against
 // previous instances with the same identity. As a special case, generic

diff --git a/src/cmd/compile/internal/types2/named.go b/src/cmd/compile/internal/types2/named.go
index 5c6a1cf5d8057942da6bf9408e4aaa8fa38b99a4..daf8fdc986103b4f3cb081dad24db92aa4d7cc5b 100644 (file)
--- a/src/cmd/compile/internal/types2/named.go
+++ b/src/cmd/compile/internal/types2/named.go
@@ -98,10 +98,10 @@ func (t *Named) cleanup() {
 }
 
 // Obj returns the type name for the declaration defining the named type t. For
-// instantiated types, this is the type name of the base type.
+// instantiated types, this is same as the type name of the origin type.
 func (t *Named) Obj() *TypeName { return t.orig.obj } // for non-instances this is the same as t.obj
 
-// Origin returns the parameterized type from which the named type t is
+// Origin returns the generic type from which the named type t is
 // instantiated. If t is not an instantiated type, the result is t.
 func (t *Named) Origin() *Named { return t.orig }
 
@@ -109,7 +109,7 @@ func (t *Named) Origin() *Named { return t.orig }
 //           between parameterized instantiated and non-instantiated types.
 
 // TypeParams returns the type parameters of the named type t, or nil.
-// The result is non-nil for an (originally) parameterized type even if it is instantiated.
+// The result is non-nil for an (originally) generic type even if it is instantiated.
 func (t *Named) TypeParams() *TypeParamList { return t.resolve(nil).tparams }
 
 // SetTypeParams sets the type parameters of the named type t.
@@ -122,7 +122,11 @@ func (t *Named) SetTypeParams(tparams []*TypeParam) {
 // TypeArgs returns the type arguments used to instantiate the named type t.
 func (t *Named) TypeArgs() *TypeList { return t.targs }
 
-// NumMethods returns the number of explicit methods whose receiver is named type t.
+// NumMethods returns the number of explicit methods defined for t.
+//
+// For an ordinary or instantiated type t, the receiver base type of these
+// methods will be the named type t. For an uninstantiated generic type t, each
+// method receiver will be instantiated with its receiver type parameters.
 func (t *Named) NumMethods() int { return t.resolve(nil).methods.Len() }
 
 // Method returns the i'th method of named type t for 0 <= i < t.NumMethods().

diff --git a/src/cmd/compile/internal/types2/typeparam.go b/src/cmd/compile/internal/types2/typeparam.go
index 9ed3369ff42f065b696a40170c780c4bd9f6f62b..2e9a2adae672c1c46d489dc42b0d069fdd2291ab 100644 (file)
--- a/src/cmd/compile/internal/types2/typeparam.go
+++ b/src/cmd/compile/internal/types2/typeparam.go
@@ -31,7 +31,8 @@ func (t *TypeParam) Obj() *TypeName { return t.obj }
 // or Signature type by calling SetTypeParams. Setting a type parameter on more
 // than one type will result in a panic.
 //
-// The constraint argument can be nil, and set later via SetConstraint.
+// The constraint argument can be nil, and set later via SetConstraint. If the
+// constraint is non-nil, it must be fully defined.
 func NewTypeParam(obj *TypeName, constraint Type) *TypeParam {
        return (*Checker)(nil).newTypeParam(obj, constraint)
 }
@@ -71,8 +72,10 @@ func (t *TypeParam) Constraint() Type {
 
 // SetConstraint sets the type constraint for t.
 //
-// SetConstraint should not be called concurrently, but once SetConstraint
-// returns the receiver t is safe for concurrent use.
+// It must be called by users of NewTypeParam after the bound's underlying is
+// fully defined, and before using the type parameter in any way other than to
+// form other types. Once SetConstraint returns the receiver, t is safe for
+// concurrent use.
 func (t *TypeParam) SetConstraint(bound Type) {
        if bound == nil {
                panic("nil constraint")

diff --git a/src/go/types/api.go b/src/go/types/api.go
index 86a03eba31f7b14f6e9d1afa1dc919fd0994a9ba..f2dcd104d85eed67e8e44d90211e94d06219ed75 100644 (file)
--- a/src/go/types/api.go
+++ b/src/go/types/api.go
@@ -199,12 +199,12 @@ type Info struct {
        // qualified identifiers are collected in the Uses map.
        Types map[ast.Expr]TypeAndValue
 
-       // Instances maps identifiers denoting parameterized types or functions to
-       // their type arguments and instantiated type.
+       // Instances maps identifiers denoting generic types or functions to their
+       // type arguments and instantiated type.
        //
        // For example, Instances will map the identifier for 'T' in the type
        // instantiation T[int, string] to the type arguments [int, string] and
-       // resulting instantiated *Named type. Given a parameterized function
+       // resulting instantiated *Named type. Given a generic function
        // func F[A any](A), Instances will map the identifier for 'F' in the call
        // expression F(int(1)) to the inferred type arguments [int], and resulting
        // instantiated *Signature.

diff --git a/src/go/types/eval.go b/src/go/types/eval.go
index c8bb005eb6d4a13d638a8aa2e8b32176411c38d1..5700cbf79c72ad4dfea4556d0fe9058a92421960 100644 (file)
--- a/src/go/types/eval.go
+++ b/src/go/types/eval.go
@@ -37,8 +37,8 @@ func Eval(fset *token.FileSet, pkg *Package, pos token.Pos, expr string) (_ Type
 
 // CheckExpr type checks the expression expr as if it had appeared at position
 // pos of package pkg. Type information about the expression is recorded in
-// info. The expression may be an uninstantiated parameterized function or
-// type.
+// info. The expression may be an identifier denoting an uninstantiated generic
+// function or type.
 //
 // If pkg == nil, the Universe scope is used and the provided
 // position pos is ignored. If pkg != nil, and pos is invalid,

diff --git a/src/go/types/instantiate.go b/src/go/types/instantiate.go
index 4b8e3d46612312a59e95ed1f15db06a9a8f9473e..a48174665739f8206504b17a8e93024c708be83e 100644 (file)
--- a/src/go/types/instantiate.go
+++ b/src/go/types/instantiate.go
@@ -15,10 +15,10 @@ import (
 
 // Instantiate instantiates the type orig with the given type arguments targs.
 // orig must be a *Named or a *Signature type. If there is no error, the
-// resulting Type is a new, instantiated (not parameterized) type of the same
-// kind (either a *Named or a *Signature). Methods attached to a *Named type
-// are also instantiated, and associated with a new *Func that has the same
-// position as the original method, but nil function scope.
+// resulting Type is an instantiated type of the same kind (either a *Named or
+// a *Signature). Methods attached to a *Named type are also instantiated, and
+// associated with a new *Func that has the same position as the original
+// method, but nil function scope.
 //
 // If ctxt is non-nil, it may be used to de-duplicate the instance against
 // previous instances with the same identity. As a special case, generic

diff --git a/src/go/types/named.go b/src/go/types/named.go
index 5b84e0653b924d2bae1672f22248687e5709461a..876f7e8551fbf3e4e035b2ae3f3dc05364ace1f1 100644 (file)
--- a/src/go/types/named.go
+++ b/src/go/types/named.go
@@ -98,12 +98,12 @@ func (t *Named) cleanup() {
 }
 
 // Obj returns the type name for the declaration defining the named type t. For
-// instantiated types, this is the type name of the base type.
+// instantiated types, this is same as the type name of the origin type.
 func (t *Named) Obj() *TypeName {
        return t.orig.obj // for non-instances this is the same as t.obj
 }
 
-// Origin returns the parameterized type from which the named type t is
+// Origin returns the generic type from which the named type t is
 // instantiated. If t is not an instantiated type, the result is t.
 func (t *Named) Origin() *Named { return t.orig }
 
@@ -111,7 +111,7 @@ func (t *Named) Origin() *Named { return t.orig }
 //           between parameterized instantiated and non-instantiated types.
 
 // TypeParams returns the type parameters of the named type t, or nil.
-// The result is non-nil for an (originally) parameterized type even if it is instantiated.
+// The result is non-nil for an (originally) generic type even if it is instantiated.
 func (t *Named) TypeParams() *TypeParamList { return t.resolve(nil).tparams }
 
 // SetTypeParams sets the type parameters of the named type t.
@@ -124,7 +124,11 @@ func (t *Named) SetTypeParams(tparams []*TypeParam) {
 // TypeArgs returns the type arguments used to instantiate the named type t.
 func (t *Named) TypeArgs() *TypeList { return t.targs }
 
-// NumMethods returns the number of explicit methods whose receiver is named type t.
+// NumMethods returns the number of explicit methods defined for t.
+//
+// For an ordinary or instantiated type t, the receiver base type of these
+// methods will be the named type t. For an uninstantiated generic type t, each
+// method receiver will be instantiated with its receiver type parameters.
 func (t *Named) NumMethods() int { return t.resolve(nil).methods.Len() }
 
 // Method returns the i'th method of named type t for 0 <= i < t.NumMethods().

diff --git a/src/go/types/typeparam.go b/src/go/types/typeparam.go
index 778c687d430ff0053eab7f934a9ddba5df816a2a..40d96ac9470ab7c6f3d47f97f1ecd9f641a16318 100644 (file)
--- a/src/go/types/typeparam.go
+++ b/src/go/types/typeparam.go
@@ -30,7 +30,8 @@ type TypeParam struct {
 // or Signature type by calling SetTypeParams. Setting a type parameter on more
 // than one type will result in a panic.
 //
-// The constraint argument can be nil, and set later via SetConstraint.
+// The constraint argument can be nil, and set later via SetConstraint. If the
+// constraint is non-nil, it must be fully defined.
 func NewTypeParam(obj *TypeName, constraint Type) *TypeParam {
        return (*Checker)(nil).newTypeParam(obj, constraint)
 }
@@ -73,8 +74,10 @@ func (t *TypeParam) Constraint() Type {
 
 // SetConstraint sets the type constraint for t.
 //
-// SetConstraint should not be called concurrently, but once SetConstraint
-// returns the receiver t is safe for concurrent use.
+// It must be called by users of NewTypeParam after the bound's underlying is
+// fully defined, and before using the type parameter in any way other than to
+// form other types. Once SetConstraint returns the receiver, t is safe for
+// concurrent use.
 func (t *TypeParam) SetConstraint(bound Type) {
        if bound == nil {
                panic("nil constraint")