Refactor XML comments for clarity in Microsoft.IdentityModel.Tokens (#…

…2689)

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

src/Microsoft.IdentityModel.Tokens/AsymmetricSecurityKey.cs

@@ -28,9 +28,13 @@ internal AsymmetricSecurityKey(SecurityKey key)
         public abstract bool HasPrivateKey { get; }
 
         /// <summary>
-        /// Gets the status of the private key.
+        /// Gets a value indicating the existence of the private key.
         /// </summary>
-        /// <return><see cref="PrivateKeyStatus.Exists"/> if private key exists for sure; <see cref="PrivateKeyStatus.DoesNotExist"/> if private key doesn't exist for sure; <see cref="PrivateKeyStatus.Unknown"/> if we cannot determine.</return>
+        /// <returns>
+        /// <see cref="PrivateKeyStatus.Exists"/> if the private key exists.
+        /// <see cref="PrivateKeyStatus.DoesNotExist"/> if the private key does not exist.
+        /// <see cref="PrivateKeyStatus.Unknown"/> if the existence of the private key cannot be determined.
+        /// </returns>
         public abstract PrivateKeyStatus PrivateKeyStatus { get; }
     }
 

src/Microsoft.IdentityModel.Tokens/AsymmetricSignatureProvider.cs

@@ -293,8 +293,8 @@ public override byte[] Sign(byte[] input, int offset, int count)
         /// Validates that an asymmetric key size is of sufficient size for a SignatureAlgorithm.
         /// </summary>
         /// <param name="key">The asymmetric key to validate.</param>
-        /// <param name="algorithm">Algorithm for which this key will be used.</param>
-        /// <param name="willCreateSignatures">Whether they key will be used for creating signatures.</param>
+        /// <param name="algorithm">The algorithm for which this key will be used.</param>
+        /// <param name="willCreateSignatures">If true, the provider will be used for creating signatures.</param>
         /// <exception cref="ArgumentNullException">Thrown if <paramref name="key"/>is null.</exception>
         /// <exception cref="ArgumentNullException">Thrown if <paramref name="algorithm"/> is null or empty.</exception>
         /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="key.KeySize"/> is less than the minimum acceptable size.</exception>

src/Microsoft.IdentityModel.Tokens/CompressionProviderFactory.cs

@@ -55,10 +55,10 @@ public static CompressionProviderFactory Default
         public ICompressionProvider CustomCompressionProvider { get; set; }
 
         /// <summary>
-        /// Checks if the specified cryptographic algorithm is supported.
+        /// Determines whether the specified algorithm is supported.
         /// </summary>
         /// <param name="algorithm">The name of the cryptographic algorithm.</param>
-        /// <returns>True if the algorithm is supported; otherwise, false.</returns>
+        /// <returns><see langword="true"/> if the algorithm is supported; otherwise, <see langword="false"/>.</returns>
         public virtual bool IsSupportedAlgorithm(string algorithm)
         {
             if (CustomCompressionProvider != null && CustomCompressionProvider.IsSupportedAlgorithm(algorithm))

src/Microsoft.IdentityModel.Tokens/CryptoProviderCache.cs

@@ -37,7 +37,7 @@ public abstract class CryptoProviderCache
         /// <param name="securityKey">The key used by the cryptographic provider.</param>
         /// <param name="algorithm">The algorithm used by the cryptographic provider.</param>
         /// <param name="typeofProvider">The type of the cryptographic provider obtained by calling object.GetType().</param>
-        /// <param name="willCreateSignatures">A boolean indicating if the <see cref="SignatureProvider"/> will be used to sign.</param>
+        /// <param name="willCreateSignatures">If true, the provider will be used for creating signatures.</param>
         /// <param name="signatureProvider">The <see cref="SignatureProvider"/> if found.</param>
         /// <returns>True if a <see cref="SignatureProvider"/> was found; false otherwise.</returns>
         public abstract bool TryGetSignatureProvider(SecurityKey securityKey, string algorithm, string typeofProvider, bool willCreateSignatures, out SignatureProvider signatureProvider);

src/Microsoft.IdentityModel.Tokens/CryptoProviderFactory.cs

@@ -626,7 +626,7 @@ internal static bool ShouldCacheSignatureProvider(SignatureProvider signaturePro
         }
 
         /// <summary>
-        /// Checks if the specified hash algorithm is supported.
+        /// Determines whether the specified hash algorithm is supported.
         /// </summary>
         /// <param name="algorithm">The name of the hash algorithm.</param>
         /// <remarks>Considers only known hash algorithms.</remarks>

src/Microsoft.IdentityModel.Tokens/DateTimeUtil.cs

@@ -6,18 +6,18 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Helper class for adding DateTimes and Timespans.
+    /// Utility class for performing operations involving <see cref="DateTime"/> and <see cref="TimeSpan"/>.
     /// </summary>
     public static class DateTimeUtil
     {
         /// <summary>
-        /// Add a DateTime and a TimeSpan.
-        /// The maximum time is DateTime.MaxTime.  It is not an error if time + timespan > MaxTime.
-        /// Just return MaxTime.
+        /// Adds a <see cref="DateTime"/> and a <see cref="TimeSpan"/>.
+        /// If the resulting value exceeds <see cref="DateTime.MaxValue"/>, returns <see cref="DateTime.MaxValue"/>.
+        /// If the resulting value is less than <see cref="DateTime.MinValue"/>, returns <see cref="DateTime.MinValue"/>.
         /// </summary>
         /// <param name="time">Initial <see cref="DateTime"/> value.</param>
         /// <param name="timespan"><see cref="TimeSpan"/> to add.</param>
-        /// <returns><see cref="DateTime"/> as the sum of time and timespan.</returns>
+        /// <returns>The sum of <paramref name="time"/> and <paramref name="timespan"/>, or <see cref="DateTime.MaxValue"/> if the sum exceeds it, or <see cref="DateTime.MinValue"/> if the sum is less than it.</returns>
         public static DateTime Add(DateTime time, TimeSpan timespan)
         {
             if (timespan == TimeSpan.Zero)
@@ -39,10 +39,10 @@ public static DateTime Add(DateTime time, TimeSpan timespan)
         }
 
         /// <summary>
-        /// Gets the Maximum value for a DateTime specifying kind.
+        /// Gets the maximum value for a <see cref="DateTime"/> with the specified <see cref="DateTimeKind"/>.
         /// </summary>
-        /// <param name="kind">DateTimeKind to use.</param>
-        /// <returns>DateTime of specified kind.</returns>
+        /// <param name="kind">The <see cref="DateTimeKind"/>.</param>
+        /// <returns>The maximum <see cref="DateTime"/> value of the specified kind.</returns>
         public static DateTime GetMaxValue(DateTimeKind kind)
         {
             if (kind == DateTimeKind.Unspecified)
@@ -52,10 +52,10 @@ public static DateTime GetMaxValue(DateTimeKind kind)
         }
 
         /// <summary>
-        /// Gets the Minimum value for a DateTime specifying kind.
+        /// Gets the minimum value for a <see cref="DateTime"/> with the specified <see cref="DateTimeKind"/>.
         /// </summary>
-        /// <param name="kind">DateTimeKind to use.</param>
-        /// <returns>DateTime of specified kind.</returns>
+        /// <param name="kind">The <see cref="DateTimeKind"/>.</param>
+        /// <returns>The minimum <see cref="DateTime"/> value of the specified kind.</returns>
         public static DateTime GetMinValue(DateTimeKind kind)
         {
             if (kind == DateTimeKind.Unspecified)
@@ -65,10 +65,10 @@ public static DateTime GetMinValue(DateTimeKind kind)
         }
 
         /// <summary>
-        /// Ensures that DataTime is UTC.
+        /// Converts the specified <see cref="DateTime"/> to UTC if it is not already in UTC.
         /// </summary>
-        /// <param name="value"><see cref="DateTime"/>to convert.</param>
-        /// <returns></returns>
+        /// <param name="value">The <see cref="DateTime"/> to convert.</param>
+        /// <returns>The converted <see cref="DateTime"/> in UTC, or null if <paramref name="value"/> is null.</returns>
         public static DateTime? ToUniversalTime(DateTime? value)
         {
             if (value == null || value.Value.Kind == DateTimeKind.Utc)
@@ -78,13 +78,12 @@ public static DateTime GetMinValue(DateTimeKind kind)
         }
 
         /// <summary>
-        /// Ensures that DateTime is UTC.
+        /// Converts the specified <see cref="DateTime"/> to UTC if it is not already in UTC.
         /// </summary>
-        /// <param name="value"><see cref="DateTime"/>to convert.</param>
-        /// <returns></returns>
+        /// <param name="value">The <see cref="DateTime"/> to convert.</param>
+        /// <returns>The converted <see cref="DateTime"/> in UTC.</returns>
         public static DateTime ToUniversalTime(DateTime value)
         {
-
             if (value.Kind == DateTimeKind.Utc)
                 return value;
 

src/Microsoft.IdentityModel.Tokens/DeflateCompressionProvider.cs

@@ -47,7 +47,7 @@ public DeflateCompressionProvider(CompressionLevel compressionLevel)
         /// <summary>
         /// Gets and sets the maximum deflate size in chars that will be processed.
         /// </summary>
-        /// <exception cref="ArgumentOutOfRangeException">'value' less than 1.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown if the value is less than 1.</exception>
         public int MaximumDeflateSize
         {
             get => _maximumTokenSizeInBytes;
@@ -58,10 +58,10 @@ public int MaximumDeflateSize
         }
 
         /// <summary>
-        /// Decompress the value using DEFLATE algorithm.
+        /// Decompresses the value using Deflate algorithm.
         /// </summary>
-        /// <param name="value">the bytes to decompress.</param>
-        /// <returns>the decompressed bytes.</returns>
+        /// <param name="value">The bytes to decompress.</param>
+        /// <returns>The decompressed bytes.</returns>
         public byte[] Decompress(byte[] value)
         {
             if (value == null)
@@ -101,10 +101,10 @@ public byte[] Decompress(byte[] value)
         }
 
         /// <summary>
-        /// Compress the value using the DEFLATE algorithm.
+        /// Compresses the value using the Deflate algorithm.
         /// </summary>
-        /// <param name="value">the bytes to compress.</param>
-        /// <returns>the compressed bytes.</returns>
+        /// <param name="value">The bytes to compress.</param>
+        /// <returns>The compressed bytes.</returns>
         public byte[] Compress(byte[] value)
         {
             if (value == null)
@@ -125,10 +125,10 @@ public byte[] Compress(byte[] value)
         }
 
         /// <summary>
-        /// Answers if a compression algorithm is supported.
+        /// Determines whether the specified compression algorithm is supported.
         /// </summary>
-        /// <param name="algorithm">the name of the compression algorithm.</param>
-        /// <returns>true if the compression algorithm is supported, false otherwise.</returns>
+        /// <param name="algorithm">The name of the compression algorithm.</param>
+        /// <returns><see langword="true"/> if the compression algorithm is supported; otherwise, <see langword="false"/>.</returns>
         public bool IsSupportedAlgorithm(string algorithm)
         {
             return Algorithm.Equals(algorithm);

src/Microsoft.IdentityModel.Tokens/ECDsaAdapter.cs

@@ -12,7 +12,7 @@ namespace Microsoft.IdentityModel.Tokens
     delegate ECDsa CreateECDsaDelegate(JsonWebKey jsonWebKey, bool usePrivateKey);
 
     /// <summary>
-    /// This adapter abstracts the <see cref="ECDsa"/> differences between versions of .Net targets.
+    /// This adapter abstracts the <see cref="ECDsa"/> differences between versions of .NET targets.
     /// </summary>
     internal class ECDsaAdapter
     {
@@ -148,10 +148,10 @@ internal static ECDsa ECDsaNotSupported(JsonWebKey jsonWebKey, bool usePrivateKe
         }
 
         /// <summary>
-        /// Returns the size of key in bytes
+        /// Determines the key size in bytes based on the specified ECDSA curve identifier.
         /// </summary>
-        /// <param name="curveId">Represents ecdsa curve -P256, P384, P521</param>
-        /// <returns>Size of the key in bytes</returns>
+        /// <param name="curveId">The identifier of the ECDSA curve (P256, P384, P521).</param>
+        /// <returns>The size of the key in bytes.</returns>
         private static uint GetKeyByteCount(string curveId)
         {
             if (string.IsNullOrEmpty(curveId))
@@ -173,11 +173,12 @@ private static uint GetKeyByteCount(string curveId)
                 default:
                     throw LogHelper.LogExceptionMessage(new ArgumentException(LogHelper.FormatInvariant(LogMessages.IDX10645, LogHelper.MarkAsNonPII(curveId))));
             }
+
             return keyByteCount;
         }
 
         /// <summary>
-        /// Magic numbers identifying ECDSA blob types
+        /// Magic numbers identifying ECDSA blob types.
         /// </summary>
         private enum KeyBlobMagicNumber : uint
         {
@@ -190,11 +191,11 @@ private enum KeyBlobMagicNumber : uint
         }
 
         /// <summary>
-        /// Returns the magic value representing the curve corresponding to the curve id.
+        /// Returns the magic value representing the curve corresponding to the curve identifier.
         /// </summary>
-        /// <param name="curveId">Represents ecdsa curve -P256, P384, P512</param>
-        /// <param name="willCreateSignatures">Whether the provider will create signatures or not</param>
-        /// <returns>Uint representing the magic number</returns>
+        /// <param name="curveId">The identifier of the ECDSA curve (P256, P384, P521).</param>
+        /// <param name="willCreateSignatures">If true, the provider will be used for creating signatures.</param>
+        /// <returns>A <see langword="uint"/> representing the magic number.</returns>
         private static uint GetMagicValue(string curveId, bool willCreateSignatures)
         {
             if (string.IsNullOrEmpty(curveId))
@@ -272,9 +273,9 @@ private static ECDsa CreateECDsaUsingECParams(JsonWebKey jsonWebKey, bool usePri
         }
 
         /// <summary>
-        /// Returns the elliptic curve corresponding to the curve id.
+        /// Returns the elliptic curve corresponding to the curve identifier.
         /// </summary>
-        /// <param name="curveId">Represents ecdsa curve -P256, P384, P512</param>
+        /// <param name="curveId">The identifier of the ECDSA curve (P256, P384, P521).</param>
         private static ECCurve GetNamedECCurve(string curveId)
         {
             if (string.IsNullOrEmpty(curveId))
@@ -311,9 +312,9 @@ internal static string GetCrvParameterValue(ECCurve curve)
 
 
         /// <summary>
-        /// Tests if user application's runtime supports <see cref="ECParameters"/> structure.
+        /// Determines whether user application's runtime supports <see cref="ECParameters"/> structure.
         /// </summary>
-        /// <returns>True if <see cref="ECParameters"/> structure is supported, false otherwise.</returns>
+        /// <returns><see langword="true"/> if <see cref="ECParameters"/> structure is supported; Otherwise <see langword="false"/>.</returns>
         internal static bool SupportsECParameters()
         {
 #if NET472 || NET6_0_OR_GREATER

src/Microsoft.IdentityModel.Tokens/ECDsaSecurityKey.cs

@@ -22,23 +22,23 @@ internal ECDsaSecurityKey(JsonWebKey webKey, bool usePrivateKey)
         }
 
         /// <summary>
-        /// Returns a new instance of <see cref="ECDsaSecurityKey"/>.
+        /// Initializes a new instance of the <see cref="ECDsaSecurityKey"/> class.
         /// </summary>
-        /// <param name="ecdsa"><see cref="System.Security.Cryptography.ECDsa"/></param>
+        /// <param name="ecdsa">The <see cref="ECDsa"/>.</param>
         public ECDsaSecurityKey(ECDsa ecdsa)
         {
             ECDsa = ecdsa ?? throw LogHelper.LogArgumentNullException(nameof(ecdsa));
         }
 
         /// <summary>
-        /// <see cref="System.Security.Cryptography.ECDsa"/> instance used to initialize the key.
+        /// The <see cref="ECDsa"/> instance used to initialize the key.
         /// </summary>
         public ECDsa ECDsa { get; private set; }
 
         /// <summary>
         /// Gets a bool indicating if a private key exists.
         /// </summary>
-        /// <return>true if it has a private key; otherwise, false.</return>
+        /// <return><see langword="true"/> if it has a private key; otherwise, <see langword="false"/>.</return>
         [System.Obsolete("HasPrivateKey method is deprecated, please use FoundPrivateKey instead.")]
         public override bool HasPrivateKey
         {
@@ -63,9 +63,13 @@ public override bool HasPrivateKey
         }
 
         /// <summary>
-        /// Gets an enum indicating if a private key exists.
+        /// Gets a value indicating the existence of the private key.
         /// </summary>
-        /// <return>'Exists' if private key exists for sure; 'DoesNotExist' if private key doesn't exist for sure; 'Unknown' if we cannot determine.</return>
+        /// <returns>
+        /// <see cref="PrivateKeyStatus.Exists"/> if the private key exists.
+        /// <see cref="PrivateKeyStatus.DoesNotExist"/> if the private key does not exist.
+        /// <see cref="PrivateKeyStatus.Unknown"/> if the existence of the private key cannot be determined.
+        /// </returns>
         public override PrivateKeyStatus PrivateKeyStatus
         {
             get
@@ -75,7 +79,7 @@ public override PrivateKeyStatus PrivateKeyStatus
         }
 
         /// <summary>
-        /// Gets <see cref="System.Security.Cryptography.ECDsa"/> key size.
+        /// Gets the <see cref="ECDsa"/> key size.
         /// </summary>
         public override int KeySize
         {
@@ -88,8 +92,8 @@ public override int KeySize
         /// <summary>
         /// Determines whether the <see cref="ECDsaSecurityKey"/> can compute a JWK thumbprint.
         /// </summary>
-        /// <returns><c>true</c> if JWK thumbprint can be computed; otherwise, <c>false</c>.</returns>
-        /// <remarks>https://datatracker.ietf.org/doc/html/rfc7638</remarks>
+        /// <returns><see langword="true"/> if JWK thumbprint can be computed; otherwise, <see langword="false"/>.</returns>
+        /// <remarks>See: <see href="https://datatracker.ietf.org/doc/html/rfc7638"/>.</remarks>
         public override bool CanComputeJwkThumbprint()
         {
 #if NET472 || NETSTANDARD2_0 || NET6_0_OR_GREATER
@@ -100,10 +104,10 @@ public override bool CanComputeJwkThumbprint()
         }
 
         /// <summary>
-        /// Computes a sha256 hash over the <see cref="ECDsaSecurityKey"/>.
+        /// Computes a SHA256 hash over the <see cref="ECDsaSecurityKey"/>.
         /// </summary>
         /// <returns>A JWK thumbprint.</returns>
-        /// <remarks>https://datatracker.ietf.org/doc/html/rfc7638</remarks>
+        /// <remarks>See: <see href="https://datatracker.ietf.org/doc/html/rfc7638"/>.</remarks>
         public override byte[] ComputeJwkThumbprint()
         {
 #if NET472 || NETSTANDARD2_0 || NET6_0_OR_GREATER