[Identity] Comment improvements. Identity generally doesn't return null anymore

sdk/identity/identity/src/credentials/authorizationCodeCredential.ts

@@ -124,10 +124,8 @@ export class AuthorizationCodeCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * @param scopes - The list of scopes for which the token will have access.
    * @param options - The options used to configure any requests this

sdk/identity/identity/src/credentials/azureCliCredential.ts

@@ -66,10 +66,8 @@ const logger = credentialLogger("AzureCliCredential");
  */
 export class AzureCliCredential implements TokenCredential {
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * @param scopes - The list of scopes for which the token will have access.
    * @param options - The options used to configure any requests this

sdk/identity/identity/src/credentials/azurePowerShellCredential.ts

@@ -134,10 +134,8 @@ export class AzurePowerShellCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful. If authentication cannot be performed at this time, this method may
-   * return null. If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If the authentication cannot be performed through PowerShell, a {@link CredentialUnavailableError} will be thrown.
    *
    * @param scopes - The list of scopes for which the token will have access.
    * @param options - The options used to configure any requests this TokenCredential implementation might make.

sdk/identity/identity/src/credentials/clientCertificateCredential.ts

@@ -49,10 +49,8 @@ export class ClientCertificateCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * @param scopes - The list of scopes for which the token will have access.
    * @param options - The options used to configure any requests this

sdk/identity/identity/src/credentials/clientSecretCredential.ts

@@ -49,10 +49,8 @@ export class ClientSecretCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * @param scopes - The list of scopes for which the token will have access.
    * @param options - The options used to configure any requests this

sdk/identity/identity/src/credentials/deviceCodeCredential.ts

@@ -45,10 +45,8 @@ export class DeviceCodeCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * If the user provided the option `disableAutomaticAuthentication`,
    * once the token can't be retrieved silently,
@@ -69,10 +67,8 @@ export class DeviceCodeCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * If the token can't be retrieved silently, this method will require user interaction to retrieve the token.
    *

sdk/identity/identity/src/credentials/environmentCredential.ts

@@ -32,6 +32,7 @@ export const AllSupportedEnvironmentVariables = [
 const logger = credentialLogger("EnvironmentCredential");
 
 /**
+ * Enables authentication to Azure Active Directory depending on the available environment variables.
  * Defines options for the EnvironmentCredential class.
  */
 export interface EnvironmentCredentialOptions
@@ -42,9 +43,17 @@ export interface EnvironmentCredentialOptions
  * Enables authentication to Azure Active Directory using client secret
  * details configured in the following environment variables:
  *
- * - AZURE_TENANT_ID: The Azure Active Directory tenant (directory) ID.
- * - AZURE_CLIENT_ID: The client (application) ID of an App Registration in the tenant.
- * - AZURE_CLIENT_SECRET: A client secret that was generated for the App Registration.
+ * Required environment variables:
+ * - `AZURE_TENANT_ID`: The Azure Active Directory tenant (directory) ID.
+ * - `AZURE_CLIENT_ID`: The client (application) ID of an App Registration in the tenant.
+ *
+ * Environment variables used for client credential authentication:
+ * - `AZURE_CLIENT_SECRET`: A client secret that was generated for the App Registration.
+ * - `AZURE_CLIENT_CERTIFICATE_PATH`: The path to a PEM certificate to use during the authentication, instead of the client secret.
+ *
+ * Alternatively, users can provide environment variables for username and password authentication:
+ * - `AZURE_USERNAME`: Username to authenticate with.
+ * - `AZURE_PASSWORD`: Password to authenticate with.
  *
  * This credential ultimately uses a {@link ClientSecretCredential} to
  * perform the authentication using these details.  Please consult the
@@ -56,10 +65,22 @@ export class EnvironmentCredential implements TokenCredential {
     | ClientCertificateCredential
     | UsernamePasswordCredential = undefined;
   /**
-   * Creates an instance of the EnvironmentCredential class and reads
-   * client secret details from environment variables.  If the expected
-   * environment variables are not found at this time, the getToken method
-   * will return null when invoked.
+   * Creates an instance of the EnvironmentCredential class and decides what credential to use depending on the available environment variables.
+   *
+   * Required environment variables:
+   * - `AZURE_TENANT_ID`: The Azure Active Directory tenant (directory) ID.
+   * - `AZURE_CLIENT_ID`: The client (application) ID of an App Registration in the tenant.
+   *
+   * Environment variables used for client credential authentication:
+   * - `AZURE_CLIENT_SECRET`: A client secret that was generated for the App Registration.
+   * - `AZURE_CLIENT_CERTIFICATE_PATH`: The path to a PEM certificate to use during the authentication, instead of the client secret.
+   *
+   * Alternatively, users can provide environment variables for username and password authentication:
+   * - `AZURE_USERNAME`: Username to authenticate with.
+   * - `AZURE_PASSWORD`: Password to authenticate with.
+   *
+   * If the environment variables required to perform the authentication are missing, a {@link CredentialUnavailableError} will be thrown.
+   * If the authentication fails, or if there's an unknown error, an {@link AuthenticationError} will be thrown.
    *
    * @param options - Options for configuring the client which makes the authentication request.
    */

sdk/identity/identity/src/credentials/interactiveBrowserCredential.browser.ts

@@ -76,10 +76,8 @@ export class InteractiveBrowserCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * If the user provided the option `disableAutomaticAuthentication`,
    * once the token can't be retrieved silently,
@@ -100,10 +98,8 @@ export class InteractiveBrowserCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * If the token can't be retrieved silently, this method will require user interaction to retrieve the token.
    *

sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts

@@ -55,10 +55,8 @@ export class InteractiveBrowserCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * If the user provided the option `disableAutomaticAuthentication`,
    * once the token can't be retrieved silently,
@@ -79,10 +77,8 @@ export class InteractiveBrowserCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * If the token can't be retrieved silently, this method will require user interaction to retrieve the token.
    *

sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts

@@ -116,10 +116,9 @@ export class ManagedIdentityCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
+   * If an unexpected error occurs, an {@link AuthenticationError} will be thrown with the details of the failure.
    *
    * @param scopes - The list of scopes for which the token will have access.
    * @param options - The options used to configure any requests this

sdk/identity/identity/src/credentials/usernamePasswordCredential.ts

@@ -52,10 +52,8 @@ export class UsernamePasswordCredential implements TokenCredential {
   }
 
   /**
-   * Authenticates with Azure Active Directory and returns an access token if
-   * successful.  If authentication cannot be performed at this time, this method may
-   * return null.  If an error occurs during authentication, an {@link AuthenticationError}
-   * containing failure details will be thrown.
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
    *
    * If the user provided the option `disableAutomaticAuthentication`,
    * once the token can't be retrieved silently,