Review comments #1.

balancer/balancer.go

@@ -111,6 +111,7 @@ type NewSubConnOptions struct {
 	// CredsBundle is the credentials bundle that will be used in the created
 	// SubConn. If it's nil, the original creds from grpc DialOptions will be
 	// used.
+	//
 	// Deprecated: Use the Attributes field in resolver.Address to pass
 	// arbitrary data to the credential handshaker.
 	CredsBundle credentials.Bundle
@@ -138,9 +139,6 @@ type ClientConn interface {
 	// NewSubConn is called by balancer to create a new SubConn.
 	// It doesn't block and wait for the connections to be established.
 	// Behaviors of the SubConn can be controlled by options.
-	//
-	// Attributes field in resolver.Address can be used to pass arbitrary data
-	// to the credential handshaker.
 	NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
 	// RemoveSubConn removes the SubConn from ClientConn.
 	// The SubConn will be shutdown.

clientconn.go

@@ -1272,11 +1272,11 @@ func (ac *addrConn) createTransport(addr resolver.Address, copts transport.Conne
 		copts.ChannelzParentID = ac.channelzID
 	}
 
-	// Balancer implementations can specify arbitrary data in the Attributes
-	// field of resolver.Address, which is shoved into connectCtx that is passed
-	// to the transport layer. The transport layer passes the same context to
-	// the credential handshaker. This makes is possible for address specific
-	// arbitrary data from balancers to reach the credential handshaker.
+	// gRPC, resolver, balancer etc. can specify arbitrary data in the
+	// Attributes field of resolver.Address, which is shoved into connectCtx
+	// that is passed to the transport layer. The transport layer passes the
+	// same context to the credential handshaker. This makes is possible for
+	// address specific arbitrary data to reach the credential handshaker.
 	connectCtx = credentials.WithAddressInfo(connectCtx, credentials.AddressInfo{Attr: addr.Attributes})
 	newTr, err := transport.NewClientTransport(connectCtx, ac.cc.ctx, addr, copts, onPrefaceReceipt, onGoAway, onClose)
 	if err != nil {

credentials/credentials.go

@@ -195,9 +195,10 @@ func RequestInfoFromContext(ctx context.Context) (ri RequestInfo, ok bool) {
 }
 
 // AddressInfo contains address related data attached to the context passed to
-// ClientHandshake. This makes it possible for balancer implementations to pass
-// arbitrary data to the handshaker. Individual credential implementations
-// control the actual format of the data that they are willing to receive.
+// ClientHandshake. This makes it possible to pass arbitrary data to the
+// handshaker from gRPC, resolver, balancer etc. Individual credential
+// implementations control the actual format of the data that they are willing
+// to receive.
 //
 // This API is experimental.
 type AddressInfo struct {