diff --git a/src/Microsoft.IdentityModel.JsonWebTokens/JsonWebTokenHandler.ValidateToken.Internal.cs b/src/Microsoft.IdentityModel.JsonWebTokens/JsonWebTokenHandler.ValidateToken.Internal.cs
index 2fd9d160c2..4b40adc8ab 100644
--- a/src/Microsoft.IdentityModel.JsonWebTokens/JsonWebTokenHandler.ValidateToken.Internal.cs
+++ b/src/Microsoft.IdentityModel.JsonWebTokens/JsonWebTokenHandler.ValidateToken.Internal.cs
@@ -17,8 +17,7 @@ public partial class JsonWebTokenHandler : TokenHandler
{
///
/// Validates a token.
- /// On a validation failure, no exception will be thrown; instead, the 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.
///
/// The token to be validated.
/// The to be used for validating the token.
diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/AlgorithmValidationError.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/AlgorithmValidationError.cs
index 0a89956bfb..d07e05a3fd 100644
--- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/AlgorithmValidationError.cs
+++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/AlgorithmValidationError.cs
@@ -8,7 +8,8 @@
namespace Microsoft.IdentityModel.Tokens
{
///
- /// 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 .
///
internal class AlgorithmValidationError : ValidationError
{
@@ -19,8 +20,8 @@ internal class AlgorithmValidationError : ValidationError
/// is the type of validation failure that occurred.
/// is the type of exception that occurred.
/// is the stack frame where the exception occurred.
- /// is the algorithm that could not be validated.
- /// is the inner exception that occurred.
+ /// is the algorithm that could not be validated. Can be null if the algorithm is missing from the token.
+ /// if present, represents the exception that occurred during validation.
public AlgorithmValidationError(
MessageDetail messageDetail,
ValidationFailureType validationFailureType,
diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/AudienceValidationError.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/AudienceValidationError.cs
index 282f508556..0dd9ab9515 100644
--- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/AudienceValidationError.cs
+++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/AudienceValidationError.cs
@@ -9,7 +9,9 @@
namespace Microsoft.IdentityModel.Tokens
{
///
- /// 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
+ /// and the allowed audiences are stored in .
///
internal class AudienceValidationError : ValidationError
{
@@ -20,9 +22,9 @@ internal class AudienceValidationError : ValidationError
/// is the type of validation failure that occurred.
/// is the type of exception that occurred.
/// is the stack frame where the exception occurred.
- /// are the audiences that were in the token.
- /// are the audiences that were expected.
- /// is the inner exception that occurred.
+ /// are the audiences that were in the token. Can be null if no audiences were found in the token.
+ /// are the audiences that were expected. Can be null if no valid audiences were provided in the validation parameters.
+ /// if present, represents the exception that occurred during validation.
public AudienceValidationError(
MessageDetail messageDetail,
ValidationFailureType validationFailureType,
diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/IssuerSigningKeyValidationError.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/IssuerSigningKeyValidationError.cs
index b4904e01f2..2251c43eb0 100644
--- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/IssuerSigningKeyValidationError.cs
+++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/IssuerSigningKeyValidationError.cs
@@ -8,7 +8,8 @@
namespace Microsoft.IdentityModel.Tokens
{
///
- /// 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 .
///
internal class IssuerSigningKeyValidationError : ValidationError
{
@@ -19,8 +20,8 @@ internal class IssuerSigningKeyValidationError : ValidationError
/// is the type of validation failure that occurred.
/// is the type of exception that occurred.
/// is the stack frame where the exception occurred.
- /// is the signing key that could not be validated.
- /// is the inner exception that occurred.
+ /// is the signing key that could not be validated. Can be null if the signing key for the token is missing.
+ /// if present, represents the exception that occurred during validation.
public IssuerSigningKeyValidationError(
MessageDetail messageDetail,
ValidationFailureType validationFailureType,
diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/IssuerValidationError.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/IssuerValidationError.cs
index 3bf1dff85a..8b384c763a 100644
--- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/IssuerValidationError.cs
+++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/IssuerValidationError.cs
@@ -8,7 +8,8 @@
namespace Microsoft.IdentityModel.Tokens
{
///
- /// 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 .
///
internal class IssuerValidationError : ValidationError
{
@@ -19,8 +20,8 @@ internal class IssuerValidationError : ValidationError
/// is the type of validation failure that occurred.
/// is the type of exception that occurred.
/// is the stack frame where the exception occurred.
- /// is the issuer that could not be validated.
- /// is the inner exception that occurred.
+ /// is the issuer that could not be validated. Can be null if the issuer is missing from the token.
+ /// if present, represents the exception that occurred during validation.
public IssuerValidationError(
MessageDetail messageDetail,
ValidationFailureType validationFailureType,
diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/LifetimeValidationError.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/LifetimeValidationError.cs
index 2fcd2901d5..38762280ad 100644
--- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/LifetimeValidationError.cs
+++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/LifetimeValidationError.cs
@@ -8,7 +8,8 @@
namespace Microsoft.IdentityModel.Tokens
{
///
- /// 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 and .
///
internal class LifetimeValidationError : ValidationError
{
@@ -19,9 +20,9 @@ internal class LifetimeValidationError : ValidationError
/// is the type of validation failure that occurred.
/// is the type of exception that occurred.
/// is the stack frame where the exception occurred.
- /// is the date from which the token is valid.
- /// is the date at which the token expires.
- /// is the inner exception that occurred.
+ /// is the date from which the token is valid. Can be null if the token does not contain a not before claim.
+ /// is the date at which the token expires. Can be null if the token does not contain an expires claim.
+ /// if present, represents the exception that occurred during validation.
public LifetimeValidationError(
MessageDetail messageDetail,
ValidationFailureType validationFailureType,
diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/SignatureValidationError.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/SignatureValidationError.cs
index 55682194d3..9d024a074f 100644
--- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/SignatureValidationError.cs
+++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/SignatureValidationError.cs
@@ -8,7 +8,7 @@
namespace Microsoft.IdentityModel.Tokens
{
///
- /// Represents a signature validation error.
+ /// Represents an error that occurs when the token's signature cannot be validated.
///
internal class SignatureValidationError : ValidationError
{
@@ -20,7 +20,7 @@ internal class SignatureValidationError : ValidationError
/// is the type of exception that occurred.
/// is the stack frame where the exception occurred.
/// if present, is the inner validation error that caused this signature validation error.
- /// is the inner exception that occurred.
+ /// if present, represents the exception that occurred during validation.
public SignatureValidationError(
MessageDetail messageDetail,
ValidationFailureType validationFailureType,
diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/TokenReplayValidationError.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/TokenReplayValidationError.cs
index 3d15068a74..125df5e6a7 100644
--- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/TokenReplayValidationError.cs
+++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/TokenReplayValidationError.cs
@@ -8,7 +8,8 @@
namespace Microsoft.IdentityModel.Tokens
{
///
- /// 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.
///
internal class TokenReplayValidationError : ValidationError
{
@@ -19,8 +20,8 @@ internal class TokenReplayValidationError : ValidationError
/// is the type of validation failure that occurred.
/// is the type of exception that occurred.
/// is the stack frame where the exception occurred.
- /// is the expiration time of the token that failed the validation.
- /// is the inner exception that occurred.
+ /// is the expiration time of the token that failed the validation. Can be null if the token does not have an expiration time.
+ /// if present, represents the exception that occurred during validation.
public TokenReplayValidationError(
MessageDetail messageDetail,
ValidationFailureType validationFailureType,
diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/TokenTypeValidationError.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/TokenTypeValidationError.cs
index c1b500d97c..1dd7d5f68a 100644
--- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/TokenTypeValidationError.cs
+++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/TokenTypeValidationError.cs
@@ -8,7 +8,8 @@
namespace Microsoft.IdentityModel.Tokens
{
///
- /// 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 .
///
internal class TokenTypeValidationError : ValidationError
{
@@ -19,8 +20,8 @@ internal class TokenTypeValidationError : ValidationError
/// is the type of validation failure that occurred.
/// is the type of exception that occurred.
/// is the stack frame where the exception occurred.
- /// is the token type that could not be validated.
- /// is the inner exception that occurred.
+ /// is the token type that could not be validated. Can be null if the token type is missing from the token.
+ /// if present, represents the exception that occurred during validation.
public TokenTypeValidationError(
MessageDetail messageDetail,
ValidationFailureType validationFailureType,
diff --git a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/ValidationError.cs b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/ValidationError.cs
index 3ad0f0b9c9..2405a1e802 100644
--- a/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/ValidationError.cs
+++ b/src/Microsoft.IdentityModel.Tokens/Validation/Results/Details/ValidationError.cs
@@ -13,7 +13,8 @@
namespace Microsoft.IdentityModel.Tokens
{
///
- /// 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 .
///
internal class ValidationError
{
@@ -28,7 +29,7 @@ internal class ValidationError
/// is the type of validation failure that occurred.
/// is the type of exception that occurred.
/// is the stack frame where the exception occurred.
- /// is the inner exception that occurred.
+ /// if present, represents the exception that occurred during validation.
internal protected ValidationError(
MessageDetail messageDetail,
ValidationFailureType validationFailureType,