Revise azidentity doc comments (Azure#17746)

Author: chlowell

sdk/azidentity/azure_cli_credential.go

@@ -27,11 +27,11 @@ type azureCLITokenProvider func(ctx context.Context, resource string, tenantID s
 
 // AzureCLICredentialOptions contains optional parameters for AzureCLICredential.
 type AzureCLICredentialOptions struct {
-	tokenProvider azureCLITokenProvider
-
 	// TenantID identifies the tenant the credential should authenticate in.
 	// Defaults to the CLI's default tenant, which is typically the home tenant of the logged in user.
 	TenantID string
+
+	tokenProvider azureCLITokenProvider
 }
 
 // init returns an instance of AzureCLICredentialOptions initialized with default values.
@@ -47,8 +47,7 @@ type AzureCLICredential struct {
 	tenantID      string
 }
 
-// NewAzureCLICredential constructs an AzureCLICredential.
-// options: Optional configuration. Pass nil to accept default settings.
+// NewAzureCLICredential constructs an AzureCLICredential. Pass nil to accept default options.
 func NewAzureCLICredential(options *AzureCLICredentialOptions) (*AzureCLICredential, error) {
 	cp := AzureCLICredentialOptions{}
 	if options != nil {
@@ -63,8 +62,6 @@ func NewAzureCLICredential(options *AzureCLICredentialOptions) (*AzureCLICredent
 
 // GetToken requests a token from the Azure CLI. This credential doesn't cache tokens, so every call invokes the CLI.
 // This method is called automatically by Azure SDK clients.
-// ctx: Context controlling the request lifetime.
-// opts: Options for the token request, in particular the desired scope of the access token.
 func (c *AzureCLICredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
 	if len(opts.Scopes) != 1 {
 		return nil, errors.New(credNameAzureCLI + ": GetToken() requires exactly one scope")

sdk/azidentity/chained_token_credential.go

@@ -17,16 +17,14 @@ import (
 
 // ChainedTokenCredentialOptions contains optional parameters for ChainedTokenCredential.
 type ChainedTokenCredentialOptions struct {
-	// RetrySources configures how the credential uses its sources.
-	// When true, the credential will always request a token from each source in turn,
-	// stopping when one provides a token. When false, the credential requests a token
-	// only from the source that previously retrieved a token--it never again tries the sources which failed.
+	// RetrySources configures how the credential uses its sources. When true, the credential always attempts to
+	// authenticate through each source in turn, stopping when one succeeds. When false, the credential authenticates
+	// only through this first successful source--it never again tries the sources which failed.
 	RetrySources bool
 }
 
-// ChainedTokenCredential is a chain of credentials that enables fallback behavior when a credential can't authenticate.
-// By default, this credential will assume that the first successful credential should be the only credential used on future requests.
-// If the `RetrySources` option is set to true, it will always try to get a token using all of the originally provided credentials.
+// ChainedTokenCredential links together multiple credentials and tries them sequentially when authenticating. By default,
+// it tries all the credentials until one authenticates, after which it always uses that credential.
 type ChainedTokenCredential struct {
 	cond                 *sync.Cond
 	iterating            bool
@@ -36,9 +34,7 @@ type ChainedTokenCredential struct {
 	successfulCredential azcore.TokenCredential
 }
 
-// NewChainedTokenCredential creates a ChainedTokenCredential.
-// sources: Credential instances to comprise the chain. GetToken() will invoke them in the given order.
-// options: Optional configuration. Pass nil to accept default settings.
+// NewChainedTokenCredential creates a ChainedTokenCredential. Pass nil for options to accept defaults.
 func NewChainedTokenCredential(sources []azcore.TokenCredential, options *ChainedTokenCredentialOptions) (*ChainedTokenCredential, error) {
 	if len(sources) == 0 {
 		return nil, errors.New("sources must contain at least one TokenCredential")
@@ -61,9 +57,8 @@ func NewChainedTokenCredential(sources []azcore.TokenCredential, options *Chaine
 	}, nil
 }
 
-// GetToken calls GetToken on the chained credentials in turn, stopping when one returns a token. This method is called automatically by Azure SDK clients.
-// ctx: Context controlling the request lifetime.
-// opts: Options for the token request, in particular the desired scope of the access token.
+// GetToken calls GetToken on the chained credentials in turn, stopping when one returns a token.
+// This method is called automatically by Azure SDK clients.
 func (c *ChainedTokenCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
 	if !c.retrySources {
 		// ensure only one goroutine at a time iterates the sources and perhaps sets c.successfulCredential

sdk/azidentity/client_certificate_credential.go

@@ -38,12 +38,7 @@ type ClientCertificateCredential struct {
 	client confidentialClient
 }
 
-// NewClientCertificateCredential constructs a ClientCertificateCredential.
-// tenantID: The application's Azure Active Directory tenant or directory ID.
-// clientID: The application's client ID.
-// certs: one or more certificates, for example as returned by ParseCertificates()
-// key: the signing certificate's private key, for example as returned by ParseCertificates()
-// options: Optional configuration. Pass nil to accept default settings.
+// NewClientCertificateCredential constructs a ClientCertificateCredential. Pass nil for options to accept defaults.
 func NewClientCertificateCredential(tenantID string, clientID string, certs []*x509.Certificate, key crypto.PrivateKey, options *ClientCertificateCredentialOptions) (*ClientCertificateCredential, error) {
 	if len(certs) == 0 {
 		return nil, errors.New("at least one certificate is required")
@@ -84,9 +79,7 @@ func NewClientCertificateCredential(tenantID string, clientID string, certs []*x
 	return &ClientCertificateCredential{client: c}, nil
 }
 
-// GetToken obtains a token from Azure Active Directory. This method is called automatically by Azure SDK clients.
-// ctx: Context controlling the request lifetime.
-// opts: Options for the token request, in particular the desired scope of the access token.
+// GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
 func (c *ClientCertificateCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
 	if len(opts.Scopes) == 0 {
 		return nil, errors.New(credNameCert + ": GetToken() requires at least one scope")
@@ -105,9 +98,8 @@ func (c *ClientCertificateCredential) GetToken(ctx context.Context, opts policy.
 	return &azcore.AccessToken{Token: ar.AccessToken, ExpiresOn: ar.ExpiresOn.UTC()}, err
 }
 
-// ParseCertificates loads certificates and a private key for use with NewClientCertificateCredential.
-// certData: certificate data encoded in PEM or PKCS12 format, including the certificate's private key.
-// password: the password required to decrypt the private key. Pass nil if the key is not encrypted. This function can't decrypt keys in PEM format.
+// ParseCertificates loads certificates and a private key, in PEM or PKCS12 format, for use with NewClientCertificateCredential.
+// Pass nil for password if the private key isn't encrypted. This function can't decrypt keys in PEM format.
 func ParseCertificates(certData []byte, password []byte) ([]*x509.Certificate, crypto.PrivateKey, error) {
 	var blocks []*pem.Block
 	var err error

sdk/azidentity/client_secret_credential.go

@@ -25,11 +25,7 @@ type ClientSecretCredential struct {
 	client confidentialClient
 }
 
-// NewClientSecretCredential constructs a ClientSecretCredential.
-// tenantID: The application's Azure Active Directory tenant or directory ID.
-// clientID: The application's client ID.
-// clientSecret: One of the application's client secrets.
-// options: Optional configuration. Pass nil to accept default settings.
+// NewClientSecretCredential constructs a ClientSecretCredential. Pass nil for options to accept defaults.
 func NewClientSecretCredential(tenantID string, clientID string, clientSecret string, options *ClientSecretCredentialOptions) (*ClientSecretCredential, error) {
 	if !validTenantID(tenantID) {
 		return nil, errors.New(tenantIDValidationErr)
@@ -55,9 +51,7 @@ func NewClientSecretCredential(tenantID string, clientID string, clientSecret st
 	return &ClientSecretCredential{client: c}, nil
 }
 
-// GetToken obtains a token from Azure Active Directory. This method is called automatically by Azure SDK clients.
-// ctx: Context used to control the request lifetime.
-// opts: Options for the token request, in particular the desired scope of the access token.
+// GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
 func (c *ClientSecretCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
 	if len(opts.Scopes) == 0 {
 		return nil, errors.New(credNameSecret + ": GetToken() requires at least one scope")

sdk/azidentity/default_azure_credential.go

@@ -28,15 +28,17 @@ type DefaultAzureCredentialOptions struct {
 // DefaultAzureCredential is a default credential chain for applications that will deploy to Azure.
 // It combines credentials suitable for deployment with credentials suitable for local development.
 // It attempts to authenticate with each of these credential types, in the following order, stopping when one provides a token:
-// - EnvironmentCredential
-// - ManagedIdentityCredential
-// - AzureCLICredential
+//  EnvironmentCredential
+//  ManagedIdentityCredential
+//  AzureCLICredential
 // Consult the documentation for these credential types for more information on how they authenticate.
+// Once a credential has successfully authenticated, DefaultAzureCredential will use that credential for
+// every subsequent authentication.
 type DefaultAzureCredential struct {
 	chain *ChainedTokenCredential
 }
 
-// NewDefaultAzureCredential creates a DefaultAzureCredential.
+// NewDefaultAzureCredential creates a DefaultAzureCredential. Pass nil for options to accept defaults.
 func NewDefaultAzureCredential(options *DefaultAzureCredentialOptions) (*DefaultAzureCredential, error) {
 	var creds []azcore.TokenCredential
 	var errorMessages []string
@@ -87,9 +89,7 @@ func NewDefaultAzureCredential(options *DefaultAzureCredentialOptions) (*Default
 	return &DefaultAzureCredential{chain: chain}, nil
 }
 
-// GetToken obtains a token from Azure Active Directory. This method is called automatically by Azure SDK clients.
-// ctx: Context used to control the request lifetime.
-// opts: Options for the token request, in particular the desired scope of the access token.
+// GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
 func (c *DefaultAzureCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (token *azcore.AccessToken, err error) {
 	return c.chain.GetToken(ctx, opts)
 }

sdk/azidentity/device_code_credential.go

@@ -69,8 +69,7 @@ type DeviceCodeCredential struct {
 	account    public.Account
 }
 
-// NewDeviceCodeCredential creates a DeviceCodeCredential.
-// options: Optional configuration. Pass nil to accept default settings.
+// NewDeviceCodeCredential creates a DeviceCodeCredential. Pass nil to accept default options.
 func NewDeviceCodeCredential(options *DeviceCodeCredentialOptions) (*DeviceCodeCredential, error) {
 	cp := DeviceCodeCredentialOptions{}
 	if options != nil {
@@ -94,10 +93,8 @@ func NewDeviceCodeCredential(options *DeviceCodeCredentialOptions) (*DeviceCodeC
 	return &DeviceCodeCredential{userPrompt: cp.UserPrompt, client: c}, nil
 }
 
-// GetToken obtains a token from Azure Active Directory. It will begin the device code flow and poll until the user completes authentication.
+// GetToken requests an access token from Azure Active Directory. It will begin the device code flow and poll until the user completes authentication.
 // This method is called automatically by Azure SDK clients.
-// ctx: Context used to control the request lifetime.
-// opts: Options for the token request, in particular the desired scope of the access token.
 func (c *DeviceCodeCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
 	if len(opts.Scopes) == 0 {
 		return nil, errors.New(credNameDeviceCode + ": GetToken() requires at least one scope")

sdk/azidentity/doc.go

@@ -25,29 +25,36 @@ type EnvironmentCredentialOptions struct {
 // EnvironmentCredential authenticates a service principal with a secret or certificate, or a user with a password, depending
 // on environment variable configuration. It reads configuration from these variables, in the following order:
 //
-// Service principal:
-// - AZURE_TENANT_ID: ID of the service principal's tenant. Also called its "directory" ID.
-// - AZURE_CLIENT_ID: the service principal's client ID
-// - AZURE_CLIENT_SECRET: one of the service principal's client secrets
+// Service principal with client secret
 //
-// Service principal with certificate:
-// - AZURE_TENANT_ID: ID of the service principal's tenant. Also called its "directory" ID.
-// - AZURE_CLIENT_ID: the service principal's client ID
-// - AZURE_CLIENT_CERTIFICATE_PATH: path to a PEM or PKCS12 certificate file including the private key. The
-//   certificate must not be password-protected.
+// AZURE_TENANT_ID: ID of the service principal's tenant. Also called its "directory" ID.
 //
-// User with username and password:
-// - AZURE_CLIENT_ID: the application's client ID
-// - AZURE_USERNAME: a username (usually an email address)
-// - AZURE_PASSWORD: that user's password
-// - AZURE_TENANT_ID: (optional) tenant to authenticate in. If not set, defaults to the "organizations" tenant, which
-//   can authenticate only Azure Active Directory work or school accounts.
+// AZURE_CLIENT_ID: the service principal's client ID
+//
+// AZURE_CLIENT_SECRET: one of the service principal's client secrets
+//
+// Service principal with certificate
+//
+// AZURE_TENANT_ID: ID of the service principal's tenant. Also called its "directory" ID.
+//
+// AZURE_CLIENT_ID: the service principal's client ID
+//
+// AZURE_CLIENT_CERTIFICATE_PATH: path to a PEM or PKCS12 certificate file including the unencrypted private key.
+//
+// User with username and password
+//
+// AZURE_TENANT_ID: (optional) tenant to authenticate in. Defaults to "organizations".
+//
+// AZURE_CLIENT_ID: client ID of the application the user will authenticate to
+//
+// AZURE_USERNAME: a username (usually an email address)
+//
+// AZURE_PASSWORD: the user's password
 type EnvironmentCredential struct {
 	cred azcore.TokenCredential
 }
 
-// NewEnvironmentCredential creates an EnvironmentCredential.
-// options: Optional configuration. Pass nil to accept default settings.
+// NewEnvironmentCredential creates an EnvironmentCredential. Pass nil to accept default options.
 func NewEnvironmentCredential(options *EnvironmentCredentialOptions) (*EnvironmentCredential, error) {
 	if options == nil {
 		options = &EnvironmentCredentialOptions{}
@@ -104,9 +111,7 @@ func NewEnvironmentCredential(options *EnvironmentCredentialOptions) (*Environme
 	return nil, errors.New("incomplete environment variable configuration. Only AZURE_TENANT_ID and AZURE_CLIENT_ID are set")
 }
 
-// GetToken obtains a token from Azure Active Directory. This method is called automatically by Azure SDK clients.
-// ctx: Context used to control the request lifetime.
-// opts: Options for the token request, in particular the desired scope of the access token.
+// GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
 func (c *EnvironmentCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
 	return c.cred.GetToken(ctx, opts)
 }

sdk/azidentity/environment_credential.go

@@ -31,11 +31,11 @@ func getResponseFromError(err error) *http.Response {
 
 // AuthenticationFailedError indicates an authentication request has failed.
 type AuthenticationFailedError struct {
-	credType string
-	message  string
-
 	// RawResponse is the HTTP response motivating the error, if available.
 	RawResponse *http.Response
+
+	credType string
+	message  string
 }
 
 func newAuthenticationFailedError(credType string, message string, resp *http.Response) AuthenticationFailedError {
@@ -47,8 +47,7 @@ func newAuthenticationFailedErrorFromMSALError(credType string, err error) Authe
 	return newAuthenticationFailedError(credType, err.Error(), res)
 }
 
-// Error implements the error interface for type ResponseError.
-// Note that the message contents are not contractual and can change over time.
+// Error implements the error interface. Note that the message contents are not contractual and can change over time.
 func (e AuthenticationFailedError) Error() string {
 	if e.RawResponse == nil {
 		return e.credType + ": " + e.message
@@ -76,7 +75,7 @@ func (e AuthenticationFailedError) Error() string {
 	return msg.String()
 }
 
-// NonRetriable indicates that this error should not be retried.
+// NonRetriable indicates the request which provoked this error shouldn't be retried.
 func (AuthenticationFailedError) NonRetriable() {
 	// marker method
 }

sdk/azidentity/errors.go

@@ -46,8 +46,7 @@ type InteractiveBrowserCredential struct {
 	account public.Account
 }
 
-// NewInteractiveBrowserCredential constructs a new InteractiveBrowserCredential.
-// options: Optional configuration. Pass nil to accept default settings.
+// NewInteractiveBrowserCredential constructs a new InteractiveBrowserCredential. Pass nil to accept default options.
 func NewInteractiveBrowserCredential(options *InteractiveBrowserCredentialOptions) (*InteractiveBrowserCredential, error) {
 	cp := InteractiveBrowserCredentialOptions{}
 	if options != nil {
@@ -71,9 +70,7 @@ func NewInteractiveBrowserCredential(options *InteractiveBrowserCredentialOption
 	return &InteractiveBrowserCredential{options: cp, client: c}, nil
 }
 
-// GetToken obtains a token from Azure Active Directory. This method is called automatically by Azure SDK clients.
-// ctx: Context used to control the request lifetime.
-// opts: Options for the token request, in particular the desired scope of the access token.
+// GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
 func (c *InteractiveBrowserCredential) GetToken(ctx context.Context, opts policy.TokenRequestOptions) (*azcore.AccessToken, error) {
 	if len(opts.Scopes) == 0 {
 		return nil, errors.New(credNameBrowser + ": GetToken() requires at least one scope")