Updated documentation

src/Microsoft.IdentityModel.JsonWebTokens/JsonWebTokenHandler.ValidateToken.Internal.cs

@@ -17,22 +17,14 @@ public partial class JsonWebTokenHandler : TokenHandler
     {
         /// <summary>
         /// Validates a token.
-        /// On a validation failure, no exception will be thrown; instead, the exception will be set in the returned TokenValidationResult.Exception property.
-        /// Callers should always check the TokenValidationResult.IsValid property to verify the validity of the result.
+        /// On a validation failure, no exception will be thrown; instead, the <see cref="ValidationError"/> will contain the information about the error that occurred.
+        /// Callers should always check the ValidationResult.IsValid property to verify the validity of the result.
         /// </summary>
         /// <param name="token">The token to be validated.</param>
         /// <param name="validationParameters">The <see cref="ValidationParameters"/> to be used for validating the token.</param>
-        /// <param name="callContext">A <see cref="CallContext"/> that contains useful information for logging.</param>
+        /// <param name="callContext">A <see cref="CallContext"/> that contains call information.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to request cancellation of the asynchronous operation.</param>
         /// <returns>A <see cref="ValidationResult{TResult}"/> with either a <see cref="ValidatedToken"/> if the token was validated or an <see cref="ValidationError"/> with the failure information and exception otherwise.</returns>
-        /// <remarks>
-        /// <para>ValidationError.GetException() will return one of the following exceptions if the <paramref name="token"/> is invalid.</para>
-        /// </remarks>
-        /// <exception cref="ArgumentNullException">Returned if <paramref name="token"/> is null or empty.</exception>
-        /// <exception cref="ArgumentNullException">Returned if <paramref name="validationParameters"/> is null.</exception>
-        /// <exception cref="ArgumentException">Returned if 'token.Length' is greater than <see cref="TokenHandler.MaximumTokenSizeInBytes"/>.</exception>
-        /// <exception cref="SecurityTokenMalformedException">Returned if <paramref name="token"/> is not a valid <see cref="JsonWebToken"/>, <see cref="ReadToken(string, CallContext)"/></exception>
-        /// <exception cref="SecurityTokenMalformedException">Returned if the validationParameters.TokenReader delegate is not able to parse/read the token as a valid <see cref="JsonWebToken"/>, <see cref="ReadToken(string, CallContext)"/></exception>
         internal async Task<ValidationResult<ValidatedToken>> ValidateTokenAsync(
             string token,
             ValidationParameters validationParameters,

src/Microsoft.IdentityModel.Tokens.Saml/Saml/SamlSecurityTokenHandler.ValidateToken.Internal.cs

@@ -14,6 +14,16 @@ namespace Microsoft.IdentityModel.Tokens.Saml
     /// </summary>
     public partial class SamlSecurityTokenHandler : SecurityTokenHandler
     {
+        /// <summary>
+        /// Validates a token.
+        /// On a validation failure, no exception will be thrown; instead, the <see cref="ValidationError"/> will contain the information about the error that occurred.
+        /// Callers should always check the ValidationResult.IsValid property to verify the validity of the result.
+        /// </summary>
+        /// <param name="token">The token to be validated.</param>
+        /// <param name="validationParameters">The <see cref="ValidationParameters"/> to be used for validating the token.</param>
+        /// <param name="callContext">A <see cref="CallContext"/> that contains call information.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to request cancellation of the asynchronous operation.</param>
+        /// <returns>A <see cref="ValidationResult{TResult}"/> with either a <see cref="ValidatedToken"/> if the token was validated or an <see cref="ValidationError"/> with the failure information and exception otherwise.</returns>
         internal async Task<ValidationResult<ValidatedToken>> ValidateTokenAsync(
             string token,
             ValidationParameters validationParameters,

src/Microsoft.IdentityModel.Tokens.Saml/Saml2/Saml2SecurityTokenHandler.ValidateToken.Internal.cs

@@ -15,6 +15,16 @@ namespace Microsoft.IdentityModel.Tokens.Saml2
     /// </summary>
     public partial class Saml2SecurityTokenHandler : SecurityTokenHandler
     {
+        /// <summary>
+        /// Validates a token.
+        /// On a validation failure, no exception will be thrown; instead, the <see cref="ValidationError"/> will contain the information about the error that occurred.
+        /// Callers should always check the ValidationResult.IsValid property to verify the validity of the result.
+        /// </summary>
+        /// <param name="token">The token to be validated.</param>
+        /// <param name="validationParameters">The <see cref="ValidationParameters"/> to be used for validating the token.</param>
+        /// <param name="callContext">A <see cref="CallContext"/> that contains call information.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to request cancellation of the asynchronous operation.</param>
+        /// <returns>A <see cref="ValidationResult{TResult}"/> with either a <see cref="ValidatedToken"/> if the token was validated or an <see cref="ValidationError"/> with the failure information and exception otherwise.</returns>
         internal async Task<ValidationResult<ValidatedToken>> ValidateTokenAsync(
             string token,
             ValidationParameters validationParameters,

src/Microsoft.IdentityModel.Tokens/Validation/Results/ValidatedToken.cs

@@ -48,27 +48,60 @@ ActorValidationResult is not null
             );
         }
 
+        /// <summary>
+        /// The <see cref="SecurityToken"/> that was validated.
+        /// </summary>
         public SecurityToken SecurityToken { get; private set; }
 
+        /// <summary>
+        /// The <see cref="TokenHandler"/> that was used to validate the token.
+        /// </summary>
         public TokenHandler TokenHandler { get; private set; }
 
+        /// <summary>
+        /// The <see cref="ValidationParameters"/> that were used to validate the token.
+        /// </summary>
         public ValidationParameters ValidationParameters { get; private set; }
 
         #region Validated Properties
+        /// <summary>
+        /// The result of validating the actor, if any.
+        /// </summary>
         public ValidatedToken? ActorValidationResult { get; internal set; }
 
+        /// <summary>
+        /// The audience that was validated, if any.
+        /// </summary>
         public string? ValidatedAudience { get; internal set; }
 
+        /// <summary>
+        /// The issuer that was validated. If present, it contains the source of the validation as well.
+        /// </summary>
         public ValidatedIssuer? ValidatedIssuer { get; internal set; }
 
+        /// <summary>
+        /// The lifetime that was validated, if any.
+        /// </summary>
         public ValidatedLifetime? ValidatedLifetime { get; internal set; }
 
+        /// <summary>
+        /// The expiration time of the token that was used to validate the token was not replayed, if any.
+        /// </summary>
         public DateTime? ValidatedTokenReplayExpirationTime { get; internal set; }
 
+        /// <summary>
+        /// The token type that was validated, if any.
+        /// </summary>
         public ValidatedTokenType? ValidatedTokenType { get; internal set; }
 
+        /// <summary>
+        /// The <see cref="SecurityKey"/> that was used to validate the token, if any.
+        /// </summary>
         public SecurityKey? ValidatedSigningKey { get; internal set; }
 
+        /// <summary>
+        /// The validated lifetime of the <see cref="SecurityKey"/> that was used to sign the token, if any.
+        /// </summary>
         public ValidatedSigningKeyLifetime? ValidatedSigningKeyLifetime { get; internal set; }
         #endregion
 
@@ -177,6 +210,9 @@ private object ClaimsIdentitySyncObj
         #endregion
 
         #region Logging
+        /// <summary>
+        /// Internal class used for logging.
+        /// </summary>
         private static class Logger
         {
             private static readonly Action<ILogger, string, string, Exception?> s_tokenValidationFailed =

src/Microsoft.IdentityModel.Tokens/Validation/Results/ValidationResult.cs

@@ -17,7 +17,8 @@ namespace Microsoft.IdentityModel.Tokens
         readonly ValidationError? _error;
 
         /// <summary>
-        /// Creates a successful, valid validation result.
+        /// Creates a new instance of <see cref="ValidationResult{TResult}"/> indicating a successful operation
+        /// and containing an object of the associated type.
         /// </summary>
         /// <param name="result">The value associated with the success.</param>
         public ValidationResult(TResult result)
@@ -28,7 +29,8 @@ public ValidationResult(TResult result)
         }
 
         /// <summary>
-        /// Creates an error, invalid validation result.
+        /// Creates a new instance of <see cref="ValidationResult{TResult}"/> indicating a failed operation
+        /// and containing a <see cref="ValidationError"/> with the error information.
         /// </summary>
         /// <param name="error">The error associated with the failure.</param>
         public ValidationResult(ValidationError error)
@@ -115,10 +117,10 @@ public TResult? Result
         }
 
         /// <summary>
-        /// 
+        /// Determines whether the specified object is equal to the current instance of <see cref="ValidationResult{TResult}"/>.
         /// </summary>
-        /// <param name="obj"></param>
-        /// <returns></returns>
+        /// <param name="obj">The object to compare with the current instance.</param>
+        /// <returns><c>true</c> if the specified object is equal to the current instance; otherwise, <c>false</c>.</returns>
         public override bool Equals(object? obj)
         {
             if (obj is ValidationResult<TResult> other)
@@ -130,10 +132,9 @@ public override bool Equals(object? obj)
         }
 
         /// <summary>
-        /// 
+        /// Returns the hash code for this instance of <see cref="ValidationResult{TResult}"/>.
         /// </summary>
-        /// <returns></returns>
-        /// <exception cref="NotImplementedException"></exception>
+        /// <returns>The hash code for the current instance.</returns>
         public override int GetHashCode()
         {
             if (IsValid)
@@ -143,32 +144,32 @@ public override int GetHashCode()
         }
 
         /// <summary>
-        /// 
+        /// Equality comparison operator for <see cref="ValidationResult{TResult}"/>.
         /// </summary>
-        /// <param name="left"></param>
-        /// <param name="right"></param>
-        /// <returns></returns>
+        /// <param name="left">The left value to compare.</param>
+        /// <param name="right">The right value to compare.</param>
+        /// <returns>A boolean indicating whether the left value is equal to the right one.</returns>
         public static bool operator ==(ValidationResult<TResult> left, ValidationResult<TResult> right)
         {
             return left.Equals(right);
         }
 
         /// <summary>
-        /// 
+        /// Inequality comparison operator for <see cref="ValidationResult{TResult}"/>.
         /// </summary>
-        /// <param name="left"></param>
-        /// <param name="right"></param>
-        /// <returns></returns>
+        /// <param name="left">The left value to compare.</param>
+        /// <param name="right">The right value to compare.</param>
+        /// <returns>A boolean indicating whether the left value is not equal to the right one.</returns>
         public static bool operator !=(ValidationResult<TResult> left, ValidationResult<TResult> right)
         {
             return !(left == right);
         }
 
         /// <summary>
-        /// 
+        /// Determines whether the specified <see cref="ValidationResult{TResult}"/> is equal to the current instance.
         /// </summary>
-        /// <param name="other"></param>
-        /// <returns></returns>
+        /// <param name="other">The <see cref="ValidationResult{TResult}"/> to compare with the current instance.</param>
+        /// <returns><c>true</c> if the specified <see cref="ValidationResult{TResult}"/> is equal to the current instance; otherwise, <c>false</c>.</returns>
         public bool Equals(ValidationResult<TResult> other)
         {
             if (other.IsValid != IsValid)

src/Microsoft.IdentityModel.Tokens/Validation/Validators.Algorithm.cs

@@ -25,6 +25,9 @@ internal delegate ValidationResult<string> AlgorithmValidationDelegate(
         ValidationParameters validationParameters,
         CallContext callContext);
 
+    /// <summary>
+    /// Partial class for Algorithm Validation.
+    /// </summary>
     public static partial class Validators
     {
         /// <summary>
@@ -34,15 +37,15 @@ public static partial class Validators
         /// <param name="securityKey">The <see cref="SecurityKey"/> that signed the <see cref="SecurityToken"/>.</param>
         /// <param name="securityToken">The <see cref="SecurityToken"/> being validated.</param>
         /// <param name="validationParameters"><see cref="ValidationParameters"/> required for validation.</param>
-        /// <param name="callContext"></param>
-#pragma warning disable CA1801 // TODO: remove pragma disable once callContext is used for logging
+        /// <param name="callContext">The <see cref="CallContext"/> that contains call information.</param>
         internal static ValidationResult<string> ValidateAlgorithm(
             string algorithm,
+#pragma warning disable CA1801
             SecurityKey securityKey,
             SecurityToken securityToken,
             ValidationParameters validationParameters,
             CallContext callContext)
-#pragma warning restore CA1801 // TODO: remove pragma disable once callContext is used for logging
+#pragma warning restore CA1801
         {
             if (validationParameters == null)
                 return ValidationError.NullParameter(

src/Microsoft.IdentityModel.Tokens/Validation/Validators.Audience.cs

@@ -35,14 +35,14 @@ public static partial class Validators
         /// <param name="tokenAudiences">The audiences found in the <see cref="SecurityToken"/>.</param>
         /// <param name="securityToken">The <see cref="SecurityToken"/> being validated.</param>
         /// <param name="validationParameters">The <see cref="TokenValidationParameters"/> to be used for validating the token.</param>
-        /// <param name="callContext"></param>
-        /// <exception cref="ArgumentNullException">If 'validationParameters' is null.</exception>
-        /// <exception cref="ArgumentNullException">If 'audiences' is null and <see cref="TokenValidationParameters.ValidateAudience"/> is true.</exception>
-        /// <exception cref="SecurityTokenInvalidAudienceException">If <see cref="TokenValidationParameters.ValidAudience"/> is null or whitespace and <see cref="TokenValidationParameters.ValidAudiences"/> is null.</exception>
-        /// <exception cref="SecurityTokenInvalidAudienceException">If none of the 'audiences' matched either <see cref="TokenValidationParameters.ValidAudience"/> or one of <see cref="TokenValidationParameters.ValidAudiences"/>.</exception>
+        /// <param name="callContext">The <see cref="CallContext"/> that contains call information.</param>
         /// <remarks>An EXACT match is required.</remarks>
-#pragma warning disable CA1801 // TODO: remove pragma disable once callContext is used for logging
-        internal static ValidationResult<string> ValidateAudience(IList<string> tokenAudiences, SecurityToken? securityToken, ValidationParameters validationParameters, CallContext callContext)
+        internal static ValidationResult<string> ValidateAudience(
+            IList<string> tokenAudiences,
+#pragma warning disable CA1801
+            SecurityToken? securityToken,
+            ValidationParameters validationParameters,
+            CallContext callContext)
 #pragma warning restore CA1801
         {
             if (validationParameters == null)

src/Microsoft.IdentityModel.Tokens/Validation/Validators.Issuer.cs

@@ -1,7 +1,6 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-using System.Diagnostics;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.IdentityModel.Logging;
@@ -27,7 +26,7 @@ internal delegate Task<ValidationResult<ValidatedIssuer>> IssuerValidationDelega
         CancellationToken cancellationToken);
 
     /// <summary>
-    /// IssuerValidation
+    /// Partial class for Issuer Validation.
     /// </summary>
     public static partial class Validators
     {
@@ -113,13 +112,7 @@ internal static async Task<ValidationResult<ValidatedIssuer>> ValidateIssuerAsyn
                     }
 
                     if (string.Equals(validationParameters.ValidIssuers[i], issuer))
-                    {
-                        // TODO: Add to CallContext
-                        //if (LogHelper.IsEnabled(EventLogLevel.Informational))
-                        //    LogHelper.LogInformation(LogMessages.IDX10236, LogHelper.MarkAsNonPII(issuer));
-
                         return new ValidatedIssuer(issuer!, IssuerValidationSource.IssuerMatchedValidationParameters);
-                    }
                 }
             }
 

src/Microsoft.IdentityModel.Tokens/Validation/Validators.IssuerSigningKey.cs

@@ -26,9 +26,8 @@ internal delegate ValidationResult<ValidatedSigningKeyLifetime> IssuerSigningKey
         CallContext callContext);
 
     /// <summary>
-    /// SigningKeyValidation
+    /// Partial class for Issuer Signing Key Validation.
     /// </summary>
-
     public static partial class Validators
     {
         /// <summary>
@@ -38,18 +37,15 @@ public static partial class Validators
         /// <param name="securityToken">The <see cref="SecurityToken"/> being validated.</param>
         /// <param name="validationParameters">The <see cref="ValidationParameters"/> to be used for validating the token.</param>
         /// <param name="configuration">The <see cref="BaseConfiguration"/> to be used for validation.</param>
-        /// <param name="callContext">The <see cref="CallContext"/> to be used for logging.</param>
-        /// <exception cref="SecurityTokenArgumentNullException"> if 'securityKey' is null and ValidateIssuerSigningKey is true.</exception>
-        /// <exception cref="SecurityTokenArgumentNullException"> if 'securityToken' is null and ValidateIssuerSigningKey is true.</exception>
-        /// <exception cref="SecurityTokenArgumentNullException"> if 'validationParameters' is null.</exception>
+        /// <param name="callContext">The <see cref="CallContext"/> that contains call information.</param>
         internal static ValidationResult<ValidatedSigningKeyLifetime> ValidateIssuerSigningKey(
             SecurityKey securityKey,
             SecurityToken securityToken,
             ValidationParameters validationParameters,
 #pragma warning disable CA1801 // Review unused parameters
             BaseConfiguration? configuration,
 #pragma warning restore CA1801 // Review unused parameters
-            CallContext? callContext)
+            CallContext callContext)
         {
             if (validationParameters == null)
                 return IssuerSigningKeyValidationError.NullParameter(
@@ -77,12 +73,12 @@ internal static ValidationResult<ValidatedSigningKeyLifetime> ValidateIssuerSign
         /// </summary>
         /// <param name="securityKey">The <see cref="SecurityKey"/> that signed the <see cref="SecurityToken"/>.</param>
         /// <param name="validationParameters">The <see cref="ValidationParameters"/> to be used for validating the token.</param>
-        /// <param name="callContext"></param>
+        /// <param name="callContext">The <see cref="CallContext"/> that contains call information.</param>
 #pragma warning disable CA1801 // Review unused parameters
         internal static ValidationResult<ValidatedSigningKeyLifetime> ValidateIssuerSigningKeyLifeTime(
             SecurityKey securityKey,
             ValidationParameters validationParameters,
-            CallContext? callContext)
+            CallContext callContext)
 #pragma warning restore CA1801 // Review unused parameters
         {
             DateTime utcNow = validationParameters.TimeProvider.GetUtcNow().UtcDateTime;