[Identity] Class documentation improvements (#32043)

This adds additional details to the docstrings for
some of the credential classes. Users may find the
added info helpful.

Also added missing envvar in README.

Signed-off-by: Paul Van Eck <paulvaneck@microsoft.com>

sdk/identity/Azure.Identity/README.md

@@ -232,6 +232,7 @@ Not all credentials require this configuration. Credentials which authenticate t
 |Variable name|Value
 |-|-
 |`AZURE_CLIENT_ID`|ID of an Azure AD application
+|`AZURE_TENANT_ID`|ID of the application's Azure AD tenant
 |`AZURE_USERNAME`|a username (usually an email address)
 |`AZURE_PASSWORD`|that user's password
 

sdk/identity/Azure.Identity/src/Credentials/EnvironmentCredential.cs

@@ -13,18 +13,39 @@
 namespace Azure.Identity
 {
     /// <summary>
-    /// Enables authentication to Azure Active Directory using client secret, or username and password,
-    /// details configured in the following environment variables:
+    /// Enables authentication to Azure Active Directory using a client secret or certificate, or as a user
+    /// with a username and password.
+    /// <para>
+    /// Configuration is attempted in this order, using these environment variables:
+    /// </para>
+    ///
+    /// <b>Service principal with secret:</b>
     /// <list type="table">
     /// <listheader><term>Variable</term><description>Description</description></listheader>
-    /// <item><term>AZURE_TENANT_ID</term><description>The Azure Active Directory tenant(directory) ID.</description></item>
-    /// <item><term>AZURE_CLIENT_ID</term><description>The client(application) ID of an App Registration in the tenant.</description></item>
+    /// <item><term>AZURE_TENANT_ID</term><description>The Azure Active Directory tenant (directory) ID.</description></item>
+    /// <item><term>AZURE_CLIENT_ID</term><description>The client (application) ID of an App Registration in the tenant.</description></item>
     /// <item><term>AZURE_CLIENT_SECRET</term><description>A client secret that was generated for the App Registration.</description></item>
+    /// </list>
+    ///
+    /// <b>Service principal with certificate:</b>
+    /// <list type="table">
+    /// <listheader><term>Variable</term><description>Description</description></listheader>
+    /// <item><term>AZURE_TENANT_ID</term><description>The Azure Active Directory tenant (directory) ID.</description></item>
+    /// <item><term>AZURE_CLIENT_ID</term><description>The client (application) ID of an App Registration in the tenant.</description></item>
     /// <item><term>AZURE_CLIENT_CERTIFICATE_PATH</term><description>A path to certificate and private key pair in PEM or PFX format, which can authenticate the App Registration.</description></item>
-    /// <item><term>AZURE_CLIENT_SEND_CERTIFICATE_CHAIN</term><description>Specifies whether an authentication request will include an x5c header to support subject name / issuer based authentication. When set to `true` or `1`, authentication requests include the x5c header.</description></item>
+    /// <item><term>AZURE_CLIENT_CERTIFICATE_PASSWORD</term><description>(Optional) The password protecting the certificate file (currently only supported for PFX (PKCS12) certificates).</description></item>
+    /// <item><term>AZURE_CLIENT_SEND_CERTIFICATE_CHAIN</term><description>(Optional) Specifies whether an authentication request will include an x5c header to support subject name / issuer based authentication. When set to `true` or `1`, authentication requests include the x5c header.</description></item>
+    /// </list>
+    ///
+    /// <b>Username and password:</b>
+    /// <list type="table">
+    /// <listheader><term>Variable</term><description>Description</description></listheader>
+    /// <item><term>AZURE_TENANT_ID</term><description>The Azure Active Directory tenant (directory) ID.</description></item>
+    /// <item><term>AZURE_CLIENT_ID</term><description>The client (application) ID of an App Registration in the tenant.</description></item>
     /// <item><term>AZURE_USERNAME</term><description>The username, also known as upn, of an Azure Active Directory user account.</description></item>
     /// <item><term>AZURE_PASSWORD</term><description>The password of the Azure Active Directory user account. Note this does not support accounts with MFA enabled.</description></item>
     /// </list>
+    ///
     /// This credential ultimately uses a <see cref="ClientSecretCredential"/>, <see cref="ClientCertificateCredential"/>, or <see cref="UsernamePasswordCredential"/> to
     /// perform the authentication using these details. Please consult the
     /// documentation of that class for more details.

sdk/identity/Azure.Identity/src/Credentials/VisualStudioCodeCredential.cs

@@ -15,7 +15,13 @@
 namespace Azure.Identity
 {
     /// <summary>
-    /// Enables authentication to Azure Active Directory using data from Visual Studio Code.
+    /// Enables authentication to Azure Active Directory as the user signed in to Visual Studio Code via
+    /// the 'Azure Account' extension.
+    ///
+    /// It's a <see href="https://github.com/Azure/azure-sdk-for-net/issues/27263">known issue</see> that `VisualStudioCodeCredential`
+    /// doesn't work with <see href="https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account">Azure Account extension</see>
+    /// versions newer than <b>0.9.11</b>. A long-term fix to this problem is in progress. In the meantime, consider authenticating
+    /// with <see cref="AzureCliCredential"/>.
     /// </summary>
     public class VisualStudioCodeCredential : TokenCredential
     {

sdk/identity/Azure.Identity/src/Credentials/VisualStudioCredential.cs

@@ -18,7 +18,9 @@
 namespace Azure.Identity
 {
     /// <summary>
-    /// Enables authentication to Azure Active Directory using data from Visual Studio
+    /// Enables authentication to Azure Active Directory using data from Visual Studio 2017 or later. See
+    /// <seealso href="https://learn.microsoft.com/dotnet/azure/configure-visual-studio" /> for more information
+    /// on how to configure Visual Studio for Azure development.
     /// </summary>
     public class VisualStudioCredential : TokenCredential
     {