Refactor XML comments for clarity in Microsoft.IdentityModel.JsonWebT…

…okens and Microsoft.IdentityModel.Protocols.OpenIdConnect (#2677)

* Refactor XML comments for clarity in Microsoft.IdentityModel.JsonWebTokens

---------

Co-authored-by: joegoldman2 <147369450+joegoldman@users.noreply.github.com>

src/Microsoft.IdentityModel.JsonWebTokens/Json/JsonClaimSet.cs

@@ -26,7 +26,10 @@ internal class JsonClaimSet
         internal readonly Dictionary<string, object> _jsonClaims;
         private List<Claim> _claims;
 
-        internal JsonClaimSet() { _jsonClaims = new Dictionary<string, object>(); }
+        internal JsonClaimSet()
+        {
+            _jsonClaims = new Dictionary<string, object>();
+        }
 
         internal JsonClaimSet(Dictionary<string, object> jsonClaims)
         {
@@ -185,16 +188,16 @@ internal T GetValue<T>(string key)
         }
 
         /// <summary>
-        /// The goal here is return types that are expected in a JWT token.
-        /// The 5 basic types: number, string, true / false, nil, array (of basic types).
-        /// This is not a general purpose translation layer for complex types.
+        /// Retrieves a value of the specified type associated with the given claim from a JWT token.
+        /// The 5 basic types: number, string, true/false, nil, array (of basic types).
+        /// This method is not designed to handle complex types.
         /// For that we would need to provide a way to hook a JsonConverter to for complex types.
         /// </summary>
-        /// <typeparam name="T"></typeparam>
-        /// <param name="key"></param>
-        /// <param name="throwEx">if this is called from TryGetValue then we don't want to throw.</param>
-        /// <param name="found"></param>
-        /// <returns></returns>
+        /// <typeparam name="T">The type of the value to retrieve.</typeparam>
+        /// <param name="key">The key associated with the claim to retrieve.</param>
+        /// <param name="throwEx">Indicates whether to throw an exception if the key is not found.</param>
+        /// <param name="found">Outputs a boolean indicating whether the key was found.</param>
+        /// <returns>The value associated with the specified key.</returns>
         internal T GetValue<T>(string key, bool throwEx, out bool found)
         {
             found = _jsonClaims.TryGetValue(key, out object obj);
@@ -412,14 +415,14 @@ internal bool TryGetClaim(string key, string issuer, out Claim claim)
 
         /// <summary>
         /// The return types that are expected in a JWT token.
-        /// The 5 basic types: number, string, true / false, nil, array (of basic types).
+        /// The 5 basic types: number, string, true/false, nil, array (of basic types).
         /// This is not a general purpose translation layer for complex types.
-        /// For that we would need to provide a way to hook a JsonConverter to for complex types.
+        /// For that, we would need to provide a way to hook a JsonConverter for complex types.
         /// </summary>
-        /// <typeparam name="T"></typeparam>
-        /// <param name="key"></param>
-        /// <param name="value"></param>
-        /// <returns></returns>
+        /// <typeparam name="T">The type of the value to retrieve.</typeparam>
+        /// <param name="key">The key associated with the value to retrieve.</param>
+        /// <param name="value">The retrieved value associated with the specified key, if found.</param>
+        /// <returns><see langword="true"/> if the key was found; otherwise, <see langword="false"/>.</returns>
         internal bool TryGetValue<T>(string key, out T value)
         {
             value = GetValue<T>(key, false, out bool found);

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

@@ -14,16 +14,13 @@
 
 namespace Microsoft.IdentityModel.JsonWebTokens
 {
-    /// <summary>
-    /// A <see cref="SecurityTokenHandler"/> designed for creating and validating Json Web Tokens.
-    /// See: https://datatracker.ietf.org/doc/html/rfc7519 and http://www.rfc-editor.org/info/rfc7515.
-    /// </summary>
+    /// <remarks>This partial class contains methods and logic related to the validation of tokens.</remarks>
     public partial class JsonWebTokenHandler : TokenHandler
     {
         /// <summary>
         /// Returns a value that indicates if this handler can validate a <see cref="SecurityToken"/>.
         /// </summary>
-        /// <returns>'true', indicating this instance can validate a <see cref="JsonWebToken"/>.</returns>
+        /// <returns><see langword="true"/> if this instance can validate a <see cref="JsonWebToken"/>.</returns>
         public virtual bool CanValidateToken
         {
             get { return true; }
@@ -40,7 +37,6 @@ internal async ValueTask<TokenValidationResult> ValidateJWEAsync(
                 if (!tokenValidationResult.IsValid)
                     return tokenValidationResult;
 
-
                 tokenValidationResult = await ValidateJWSAsync(
                     tokenValidationResult.SecurityToken as JsonWebToken,
                     validationParameters,
@@ -502,9 +498,9 @@ private static JsonWebToken ValidateSignatureUsingDelegates(JsonWebToken jsonWeb
         /// <summary>
         /// Validates a JWS or a JWE.
         /// </summary>
-        /// <param name="token">A 'JSON Web Token' (JWT) in JWS or JWE Compact Serialization Format.</param>
-        /// <param name="validationParameters">A <see cref="TokenValidationParameters"/>  required for validation.</param>
-        /// <returns>A <see cref="TokenValidationResult"/></returns>
+        /// <param name="token">A JSON Web Token (JWT) in JWS or JWE Compact Serialization format.</param>
+        /// <param name="validationParameters">A <see cref="TokenValidationParameters"/> required for validation.</param>
+        /// <returns>A <see cref="TokenValidationResult"/>.</returns>
         [Obsolete("`JsonWebTokens.ValidateToken(string, TokenValidationParameters)` has been deprecated and will be removed in a future release. Use `JsonWebTokens.ValidateTokenAsync(string, TokenValidationParameters)` instead. For more information, see https://aka.ms/IdentityModel/7-breaking-changes", false)]
         public virtual TokenValidationResult ValidateToken(string token, TokenValidationParameters validationParameters)
         {
@@ -518,15 +514,15 @@ public virtual TokenValidationResult ValidateToken(string token, TokenValidation
         /// </summary>
         /// <param name="token">The token to be validated.</param>
         /// <param name="validationParameters">A <see cref="TokenValidationParameters"/> required for validation.</param>
-        /// <returns>A <see cref="TokenValidationResult"/></returns>
+        /// <returns>A <see cref="TokenValidationResult"/>.</returns>
         /// <remarks>
-        /// <para>TokenValidationResult.Exception will be set to one of the following exceptions if the  <paramref name="token"/> is invalid.</para>
-        /// <para><exception cref="ArgumentNullException">if <paramref name="token"/> is null or empty.</exception></para>
-        /// <para><exception cref="ArgumentNullException">if <paramref name="validationParameters"/> is null.</exception></para>
-        /// <para><exception cref="ArgumentException">'token.Length' is greater than <see cref="TokenHandler.MaximumTokenSizeInBytes"/>.</exception></para>
-        /// <para><exception cref="SecurityTokenMalformedException">if <paramref name="token"/> is not a valid <see cref="JsonWebToken"/>, <see cref="ReadToken(string, TokenValidationParameters)"/></exception></para>
-        /// <para><exception cref="SecurityTokenMalformedException">if the validationParameters.TokenReader delegate is not able to parse/read the token as a valid <see cref="JsonWebToken"/>, <see cref="ReadToken(string, TokenValidationParameters)"/></exception></para>
+        /// <para>TokenValidationResult.Exception will be set to one of the following exceptions if the <paramref name="token"/> is invalid.</para>
         /// </remarks>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="token"/> is null or empty.</exception>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="validationParameters"/> is null.</exception>
+        /// <exception cref="ArgumentException">Thrown if 'token.Length' is greater than <see cref="TokenHandler.MaximumTokenSizeInBytes"/>.</exception>
+        /// <exception cref="SecurityTokenMalformedException">Thrown if <paramref name="token"/> is not a valid <see cref="JsonWebToken"/>, <see cref="ReadToken(string, TokenValidationParameters)"/></exception>
+        /// <exception cref="SecurityTokenMalformedException">Thrown if the validationParameters.TokenReader delegate is not able to parse/read the token as a valid <see cref="JsonWebToken"/>, <see cref="ReadToken(string, TokenValidationParameters)"/></exception>
         public override async Task<TokenValidationResult> ValidateTokenAsync(string token, TokenValidationParameters validationParameters)
         {
             if (string.IsNullOrEmpty(token))
@@ -588,8 +584,8 @@ public override async Task<TokenValidationResult> ValidateTokenAsync(SecurityTok
         ///  (1) Obtaining a configuration from the <see cref="TokenValidationParameters.ConfigurationManager"/>.
         ///  (2) Revalidating using the Last Known Good Configuration (if present), and obtaining a refreshed configuration (if necessary) and revalidating using it.
         /// </summary>
-        /// <param name="jsonWebToken">The JWT token</param>
-        /// <param name="validationParameters">The <see cref="TokenValidationParameters"/> to be used for validation.</param>
+        /// <param name="jsonWebToken">The JWT token.</param>
+        /// <param name="validationParameters">The <see cref="TokenValidationParameters"/> to be used for validating the token.</param>
         /// <returns></returns>
         internal async ValueTask<TokenValidationResult> ValidateTokenAsync(
             JsonWebToken jsonWebToken,