all: modernize with doc links and any

Change-Id: If3fc4542b92da802a31dcabc3405f7b1ab06a18d
Reviewed-on: https://go-review.googlesource.com/c/oauth2/+/666396
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Junyang Shao <shaojunyang@google.com>
Reviewed-by: Michael Pratt <mpratt@google.com>
Auto-Submit: Sean Liao <sean@liao.dev>
Reviewed-by: Matt Hickford <matt.hickford@gmail.com>

Author: seankhliao

authhandler/authhandler.go

@@ -34,7 +34,7 @@ type PKCEParams struct {
 // and returns an auth code and state upon approval.
 type AuthorizationHandler func(authCodeURL string) (code string, state string, err error)
 
-// TokenSourceWithPKCE is an enhanced version of TokenSource with PKCE support.
+// TokenSourceWithPKCE is an enhanced version of [oauth2.TokenSource] with PKCE support.
 //
 // The pkce parameter supports PKCE flow, which uses code challenge and code verifier
 // to prevent CSRF attacks. A unique code challenge and code verifier should be generated
@@ -43,12 +43,12 @@ func TokenSourceWithPKCE(ctx context.Context, config *oauth2.Config, state strin
 	return oauth2.ReuseTokenSource(nil, authHandlerSource{config: config, ctx: ctx, authHandler: authHandler, state: state, pkce: pkce})
 }
 
-// TokenSource returns an oauth2.TokenSource that fetches access tokens
+// TokenSource returns an [oauth2.TokenSource] that fetches access tokens
 // using 3-legged-OAuth flow.
 //
-// The provided context.Context is used for oauth2 Exchange operation.
+// The provided [context.Context] is used for oauth2 Exchange operation.
 //
-// The provided oauth2.Config should be a full configuration containing AuthURL,
+// The provided [oauth2.Config] should be a full configuration containing AuthURL,
 // TokenURL, and Scope.
 //
 // An environment-specific AuthorizationHandler is used to obtain user consent.

clientcredentials/clientcredentials.go

@@ -55,7 +55,7 @@ type Config struct {
 
 // Token uses client credentials to retrieve a token.
 //
-// The provided context optionally controls which HTTP client is used. See the oauth2.HTTPClient variable.
+// The provided context optionally controls which HTTP client is used. See the [oauth2.HTTPClient] variable.
 func (c *Config) Token(ctx context.Context) (*oauth2.Token, error) {
 	return c.TokenSource(ctx).Token()
 }
@@ -64,18 +64,18 @@ func (c *Config) Token(ctx context.Context) (*oauth2.Token, error) {
 // The token will auto-refresh as necessary.
 //
 // The provided context optionally controls which HTTP client
-// is returned. See the oauth2.HTTPClient variable.
+// is returned. See the [oauth2.HTTPClient] variable.
 //
-// The returned Client and its Transport should not be modified.
+// The returned [http.Client] and its Transport should not be modified.
 func (c *Config) Client(ctx context.Context) *http.Client {
 	return oauth2.NewClient(ctx, c.TokenSource(ctx))
 }
 
-// TokenSource returns a TokenSource that returns t until t expires,
+// TokenSource returns a [oauth2.TokenSource] that returns t until t expires,
 // automatically refreshing it as necessary using the provided context and the
 // client ID and client secret.
 //
-// Most users will use Config.Client instead.
+// Most users will use [Config.Client] instead.
 func (c *Config) TokenSource(ctx context.Context) oauth2.TokenSource {
 	source := &tokenSource{
 		ctx:  ctx,

google/externalaccount/basecredentials.go

@@ -486,11 +486,11 @@ func (ts tokenSource) Token() (*oauth2.Token, error) {
 		ClientID:     conf.ClientID,
 		ClientSecret: conf.ClientSecret,
 	}
-	var options map[string]interface{}
+	var options map[string]any
 	// Do not pass workforce_pool_user_project when client authentication is used.
 	// The client ID is sufficient for determining the user project.
 	if conf.WorkforcePoolUserProject != "" && conf.ClientID == "" {
-		options = map[string]interface{}{
+		options = map[string]any{
 			"userProject": conf.WorkforcePoolUserProject,
 		}
 	}

google/externalaccount/filecredsource.go

@@ -35,7 +35,7 @@ func (cs fileCredentialSource) subjectToken() (string, error) {
 	tokenBytes = bytes.TrimSpace(tokenBytes)
 	switch cs.Format.Type {
 	case "json":
-		jsonData := make(map[string]interface{})
+		jsonData := make(map[string]any)
 		err = json.Unmarshal(tokenBytes, &jsonData)
 		if err != nil {
 			return "", fmt.Errorf("oauth2/google/externalaccount: failed to unmarshal subject token file: %v", err)

google/externalaccount/urlcredsource.go

@@ -53,7 +53,7 @@ func (cs urlCredentialSource) subjectToken() (string, error) {
 
 	switch cs.Format.Type {
 	case "json":
-		jsonData := make(map[string]interface{})
+		jsonData := make(map[string]any)
 		err = json.Unmarshal(respBody, &jsonData)
 		if err != nil {
 			return "", fmt.Errorf("oauth2/google/externalaccount: failed to unmarshal subject token file: %v", err)

google/google.go

@@ -301,7 +301,7 @@ func (cs computeSource) Token() (*oauth2.Token, error) {
 	// NOTE(cbro): add hidden metadata about where the token is from.
 	// This is needed for detection by client libraries to know that credentials come from the metadata server.
 	// This may be removed in a future version of this library.
-	return tok.WithExtra(map[string]interface{}{
+	return tok.WithExtra(map[string]any{
 		"oauth2.google.tokenSource":    "compute-metadata",
 		"oauth2.google.serviceAccount": acct,
 	}), nil

google/internal/stsexchange/sts_exchange.go

@@ -27,7 +27,7 @@ func defaultHeader() http.Header {
 // The first 4 fields are all mandatory.  headers can be used to pass additional
 // headers beyond the bare minimum required by the token exchange.  options can
 // be used to pass additional JSON-structured options to the remote server.
-func ExchangeToken(ctx context.Context, endpoint string, request *TokenExchangeRequest, authentication ClientAuthentication, headers http.Header, options map[string]interface{}) (*Response, error) {
+func ExchangeToken(ctx context.Context, endpoint string, request *TokenExchangeRequest, authentication ClientAuthentication, headers http.Header, options map[string]any) (*Response, error) {
 	data := url.Values{}
 	data.Set("audience", request.Audience)
 	data.Set("grant_type", "urn:ietf:params:oauth:grant-type:token-exchange")

google/internal/stsexchange/sts_exchange_test.go

@@ -146,7 +146,7 @@ func TestExchangeToken_Opts(t *testing.T) {
 		} else if len(strOpts) < 1 {
 			t.Errorf("\"options\" field has length 0.")
 		}
-		var opts map[string]interface{}
+		var opts map[string]any
 		err = json.Unmarshal([]byte(strOpts[0]), &opts)
 		if err != nil {
 			t.Fatalf("Couldn't parse received \"options\" field.")
@@ -159,7 +159,7 @@ func TestExchangeToken_Opts(t *testing.T) {
 		if !ok {
 			t.Errorf("Couldn't find first option parameter.")
 		} else {
-			tOpts1, ok := val.(map[string]interface{})
+			tOpts1, ok := val.(map[string]any)
 			if !ok {
 				t.Errorf("Failed to assert the first option parameter as type testOpts.")
 			} else {
@@ -176,7 +176,7 @@ func TestExchangeToken_Opts(t *testing.T) {
 		if !ok {
 			t.Errorf("Couldn't find second option parameter.")
 		} else {
-			tOpts2, ok := val2.(map[string]interface{})
+			tOpts2, ok := val2.(map[string]any)
 			if !ok {
 				t.Errorf("Failed to assert the second option parameter as type testOpts.")
 			} else {
@@ -200,7 +200,7 @@ func TestExchangeToken_Opts(t *testing.T) {
 
 	firstOption := testOpts{optsValues[0][0], optsValues[0][1]}
 	secondOption := testOpts{optsValues[1][0], optsValues[1][1]}
-	inputOpts := make(map[string]interface{})
+	inputOpts := make(map[string]any)
 	inputOpts["one"] = firstOption
 	inputOpts["two"] = secondOption
 	ExchangeToken(context.Background(), ts.URL, &exchangeTokenRequest, auth, headers, inputOpts)

internal/doc.go

@@ -2,5 +2,5 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package internal contains support packages for oauth2 package.
+// Package internal contains support packages for [golang.org/x/oauth2].
 package internal

internal/oauth2.go

@@ -13,7 +13,7 @@ import (
 )
 
 // ParseKey converts the binary contents of a private key file
-// to an *rsa.PrivateKey. It detects whether the private key is in a
+// to an [*rsa.PrivateKey]. It detects whether the private key is in a
 // PEM container or not. If so, it extracts the private key
 // from PEM container before conversion. It only supports PEM
 // containers with no passphrase.

internal/token.go

@@ -25,9 +25,9 @@ import (
 // the requests to access protected resources on the OAuth 2.0
 // provider's backend.
 //
-// This type is a mirror of oauth2.Token and exists to break
+// This type is a mirror of [golang.org/x/oauth2.Token] and exists to break
 // an otherwise-circular dependency. Other internal packages
-// should convert this Token into an oauth2.Token before use.
+// should convert this Token into an [golang.org/x/oauth2.Token] before use.
 type Token struct {
 	// AccessToken is the token that authorizes and authenticates
 	// the requests.
@@ -58,7 +58,7 @@ type Token struct {
 
 	// Raw optionally contains extra metadata from the server
 	// when updating a token.
-	Raw interface{}
+	Raw any
 }
 
 // tokenJSON is the struct representing the HTTP response from OAuth2
@@ -319,7 +319,7 @@ func doTokenRoundTrip(ctx context.Context, req *http.Request) (*Token, error) {
 			RefreshToken: tj.RefreshToken,
 			Expiry:       tj.expiry(),
 			ExpiresIn:    int64(tj.ExpiresIn),
-			Raw:          make(map[string]interface{}),
+			Raw:          make(map[string]any),
 		}
 		json.Unmarshal(body, &token.Raw) // no error checks for optional fields
 	}

internal/transport.go

@@ -9,8 +9,8 @@ import (
 	"net/http"
 )
 
-// HTTPClient is the context key to use with [context.WithValue]'s
-// function to associate an *http.Client value with a context.
+// HTTPClient is the context key to use with [context.WithValue]
+// to associate an [*http.Client] value with a context.
 var HTTPClient ContextKey
 
 // ContextKey is just an empty struct. It exists so HTTPClient can be

jws/jws.go

@@ -4,7 +4,7 @@
 
 // Package jws provides a partial implementation
 // of JSON Web Signature encoding and decoding.
-// It exists to support the golang.org/x/oauth2 package.
+// It exists to support the [golang.org/x/oauth2] package.
 //
 // See RFC 7515.
 //
@@ -48,7 +48,7 @@ type ClaimSet struct {
 
 	// See http://tools.ietf.org/html/draft-jones-json-web-token-10#section-4.3
 	// This array is marshalled using custom code (see (c *ClaimSet) encode()).
-	PrivateClaims map[string]interface{} `json:"-"`
+	PrivateClaims map[string]any `json:"-"`
 }
 
 func (c *ClaimSet) encode() (string, error) {
@@ -152,7 +152,7 @@ func EncodeWithSigner(header *Header, c *ClaimSet, sg Signer) (string, error) {
 }
 
 // Encode encodes a signed JWS with provided header and claim set.
-// This invokes EncodeWithSigner using crypto/rsa.SignPKCS1v15 with the given RSA private key.
+// This invokes [EncodeWithSigner] using [crypto/rsa.SignPKCS1v15] with the given RSA private key.
 func Encode(header *Header, c *ClaimSet, key *rsa.PrivateKey) (string, error) {
 	sg := func(data []byte) (sig []byte, err error) {
 		h := sha256.New()

jwt/jwt.go

@@ -68,7 +68,7 @@ type Config struct {
 
 	// PrivateClaims optionally specifies custom private claims in the JWT.
 	// See http://tools.ietf.org/html/draft-jones-json-web-token-10#section-4.3
-	PrivateClaims map[string]interface{}
+	PrivateClaims map[string]any
 
 	// UseIDToken optionally specifies whether ID token should be used instead
 	// of access token when the server returns both.
@@ -157,7 +157,7 @@ func (js jwtSource) Token() (*oauth2.Token, error) {
 		AccessToken: tokenRes.AccessToken,
 		TokenType:   tokenRes.TokenType,
 	}
-	raw := make(map[string]interface{})
+	raw := make(map[string]any)
 	json.Unmarshal(body, &raw) // no error checks for optional fields
 	token = token.WithExtra(raw)
 

jwt/jwt_test.go

@@ -227,7 +227,7 @@ func TestJWTFetch_AssertionPayload(t *testing.T) {
 			PrivateKey:   dummyPrivateKey,
 			PrivateKeyID: "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
 			TokenURL:     ts.URL,
-			PrivateClaims: map[string]interface{}{
+			PrivateClaims: map[string]any{
 				"private0": "claim0",
 				"private1": "claim1",
 			},
@@ -273,11 +273,11 @@ func TestJWTFetch_AssertionPayload(t *testing.T) {
 				t.Errorf("payload prn = %q; want %q", got, want)
 			}
 			if len(conf.PrivateClaims) > 0 {
-				var got interface{}
+				var got any
 				if err := json.Unmarshal(gotjson, &got); err != nil {
 					t.Errorf("failed to parse payload; err = %q", err)
 				}
-				m := got.(map[string]interface{})
+				m := got.(map[string]any)
 				for v, k := range conf.PrivateClaims {
 					if !reflect.DeepEqual(m[v], k) {
 						t.Errorf("payload private claims key = %q: got %#v; want %#v", v, m[v], k)