Updated documentation based on PR feedback

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

@@ -17,8 +17,7 @@ public partial class JsonWebTokenHandler : TokenHandler
     {
         /// <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.
+        /// On validation failure no exception will be thrown. 'see cref="ValidationError"' will contain information pertaining to the error.
         /// </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>

src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/AlgorithmValidationError.cs

@@ -8,7 +8,8 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Represents an algorithm validation error.
+    /// Represents a validation error that occurs when a token's algorithm cannot be validated.
+    /// If available, the invalid algorithm is stored in <see cref="InvalidAlgorithm"/>.
     /// </summary>
     internal class AlgorithmValidationError : ValidationError
     {
@@ -19,8 +20,8 @@ internal class AlgorithmValidationError : ValidationError
         /// <param name="validationFailureType"/> is the type of validation failure that occurred.
         /// <param name="exceptionType"/> is the type of exception that occurred.
         /// <param name="stackFrame"/> is the stack frame where the exception occurred.
-        /// <param name="invalidAlgorithm"/> is the algorithm that could not be validated.
-        /// <param name="innerException"/> is the inner exception that occurred.
+        /// <param name="invalidAlgorithm"/> is the algorithm that could not be validated. Can be null if the algorithm is missing from the token.
+        /// <param name="innerException"/> if present, represents the exception that occurred during validation.
         public AlgorithmValidationError(
             MessageDetail messageDetail,
             ValidationFailureType validationFailureType,

src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/AudienceValidationError.cs

@@ -9,7 +9,9 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Represents an audience validation error.
+    /// Represents an error that occurs when the token's audience cannot be validated.
+    /// If available, the invalid audiences from the token are stored in <see cref="TokenAudiences"/>
+    /// and the allowed audiences are stored in <see cref="ValidAudiences"/>.
     /// </summary>
     internal class AudienceValidationError : ValidationError
     {
@@ -20,9 +22,9 @@ internal class AudienceValidationError : ValidationError
         /// <param name="validationFailureType"/> is the type of validation failure that occurred.
         /// <param name="exceptionType"/> is the type of exception that occurred.
         /// <param name="stackFrame"/> is the stack frame where the exception occurred.
-        /// <param name="tokenAudiences"/> are the audiences that were in the token.
-        /// <param name="validAudiences"/> are the audiences that were expected.
-        /// <param name="innerException"/> is the inner exception that occurred.
+        /// <param name="tokenAudiences"/> are the audiences that were in the token. Can be null if no audiences were found in the token.
+        /// <param name="validAudiences"/> are the audiences that were expected. Can be null if no valid audiences were provided in the validation parameters.
+        /// <param name="innerException"/> if present, represents the exception that occurred during validation.
         public AudienceValidationError(
             MessageDetail messageDetail,
             ValidationFailureType validationFailureType,

src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/IssuerSigningKeyValidationError.cs

@@ -8,7 +8,8 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Represents an issuer signing key validation error.
+    /// Represents a validation error that occurs when the issuer signing key cannot be validated.
+    /// If available, the invalid signing key is stored in <see cref="InvalidSigningKey"/>.
     /// </summary>
     internal class IssuerSigningKeyValidationError : ValidationError
     {
@@ -19,8 +20,8 @@ internal class IssuerSigningKeyValidationError : ValidationError
         /// <param name="validationFailureType"/> is the type of validation failure that occurred.
         /// <param name="exceptionType"/> is the type of exception that occurred.
         /// <param name="stackFrame"/> is the stack frame where the exception occurred.
-        /// <param name="invalidSigningKey"/> is the signing key that could not be validated.
-        /// <param name="innerException"/> is the inner exception that occurred.
+        /// <param name="invalidSigningKey"/> is the signing key that could not be validated. Can be null if the signing key for the token is missing.
+        /// <param name="innerException"/> if present, represents the exception that occurred during validation.
         public IssuerSigningKeyValidationError(
             MessageDetail messageDetail,
             ValidationFailureType validationFailureType,

src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/IssuerValidationError.cs

@@ -8,7 +8,8 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Represents an issuer validation error.
+    /// Represents an error that occurs when the issuer of a token cannot be validated.
+    /// If available, the invalid issuer is stored in <see cref="InvalidIssuer"/>.
     /// </summary>
     internal class IssuerValidationError : ValidationError
     {
@@ -19,8 +20,8 @@ internal class IssuerValidationError : ValidationError
         /// <param name="validationFailureType"/> is the type of validation failure that occurred.
         /// <param name="exceptionType"/> is the type of exception that occurred.
         /// <param name="stackFrame"/> is the stack frame where the exception occurred.
-        /// <param name="invalidIssuer"/> is the issuer that could not be validated.
-        /// <param name="innerException"/> is the inner exception that occurred.
+        /// <param name="invalidIssuer"/> is the issuer that could not be validated. Can be null if the issuer is missing from the token.
+        /// <param name="innerException"/> if present, represents the exception that occurred during validation.
         public IssuerValidationError(
             MessageDetail messageDetail,
             ValidationFailureType validationFailureType,

src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/LifetimeValidationError.cs

@@ -8,7 +8,8 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Represents a lifetime validation error.
+    /// Represents an error that occurs when a token's lifetime cannot be validated.
+    /// If available, the not before and expires values are stored in <see cref="NotBefore"/> and <see cref="Expires"/>.
     /// </summary>
     internal class LifetimeValidationError : ValidationError
     {
@@ -19,9 +20,9 @@ internal class LifetimeValidationError : ValidationError
         /// <param name="validationFailureType"/> is the type of validation failure that occurred.
         /// <param name="exceptionType"/> is the type of exception that occurred.
         /// <param name="stackFrame"/> is the stack frame where the exception occurred.
-        /// <param name="notBefore"/> is the date from which the token is valid.
-        /// <param name="expires"/> is the date at which the token expires.
-        /// <param name="innerException"/> is the inner exception that occurred.
+        /// <param name="notBefore"/> is the date from which the token is valid. Can be null if the token does not contain a not before claim.
+        /// <param name="expires"/> is the date at which the token expires. Can be null if the token does not contain an expires claim.
+        /// <param name="innerException"/> if present, represents the exception that occurred during validation.
         public LifetimeValidationError(
             MessageDetail messageDetail,
             ValidationFailureType validationFailureType,

src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/SignatureValidationError.cs

@@ -8,7 +8,7 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Represents a signature validation error.
+    /// Represents an error that occurs when the token's signature cannot be validated.
     /// </summary>
     internal class SignatureValidationError : ValidationError
     {
@@ -20,7 +20,7 @@ internal class SignatureValidationError : ValidationError
         /// <param name="exceptionType"/> is the type of exception that occurred.
         /// <param name="stackFrame"/> is the stack frame where the exception occurred.
         /// <param name="innerValidationError"/> if present, is the inner validation error that caused this signature validation error.
-        /// <param name="innerException"/> is the inner exception that occurred.
+        /// <param name="innerException"/> if present, represents the exception that occurred during validation.
         public SignatureValidationError(
             MessageDetail messageDetail,
             ValidationFailureType validationFailureType,

src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/TokenReplayValidationError.cs

@@ -8,7 +8,8 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Represents a token replay validation error.
+    /// Represents an error that occurs when a token cannot be validated against being re-used or replay is detected.
+    /// If available, the expiration time of the token that failed the validation is included.
     /// </summary>
     internal class TokenReplayValidationError : ValidationError
     {
@@ -19,8 +20,8 @@ internal class TokenReplayValidationError : ValidationError
         /// <param name="validationFailureType"/> is the type of validation failure that occurred.
         /// <param name="exceptionType"/> is the type of exception that occurred.
         /// <param name="stackFrame"/> is the stack frame where the exception occurred.
-        /// <param name="expirationTime"/> is the expiration time of the token that failed the validation.
-        /// <param name="innerException"/> is the inner exception that occurred.
+        /// <param name="expirationTime"/> is the expiration time of the token that failed the validation. Can be null if the token does not have an expiration time.
+        /// <param name="innerException"/> if present, represents the exception that occurred during validation.
         public TokenReplayValidationError(
             MessageDetail messageDetail,
             ValidationFailureType validationFailureType,

src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/TokenTypeValidationError.cs

@@ -8,7 +8,8 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Represents a token type validation error.
+    /// Represents an error that occurs when a token type cannot be validated.
+    /// If available, the invalid token type is stored in <see cref="InvalidTokenType"/>.
     /// </summary>
     internal class TokenTypeValidationError : ValidationError
     {
@@ -19,8 +20,8 @@ internal class TokenTypeValidationError : ValidationError
         /// <param name="validationFailureType"/> is the type of validation failure that occurred.
         /// <param name="exceptionType"/> is the type of exception that occurred.
         /// <param name="stackFrame"/> is the stack frame where the exception occurred.
-        /// <param name="invalidTokenType"/> is the token type that could not be validated.
-        /// <param name="innerException"/> is the inner exception that occurred.
+        /// <param name="invalidTokenType"/> is the token type that could not be validated. Can be null if the token type is missing from the token.
+        /// <param name="innerException"/> if present, represents the exception that occurred during validation.
         public TokenTypeValidationError(
             MessageDetail messageDetail,
             ValidationFailureType validationFailureType,

src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/ValidationError.cs

@@ -13,7 +13,8 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Contains information so that Exceptions can be logged or thrown written as required.
+    /// Represents an error that occurred during token validation.
+    /// If necessary, it can be used to create an instance of <see cref="Exception"/>.
     /// </summary>
     internal class ValidationError
     {
@@ -28,7 +29,7 @@ internal class ValidationError
         /// <param name="validationFailureType"/> is the type of validation failure that occurred.
         /// <param name="exceptionType"/> is the type of exception that occurred.
         /// <param name="stackFrame"/> is the stack frame where the exception occurred.
-        /// <param name="innerException"/> is the inner exception that occurred.
+        /// <param name="innerException"/> if present, represents the exception that occurred during validation.
         internal protected ValidationError(
             MessageDetail messageDetail,
             ValidationFailureType validationFailureType,