Refactor XML comments for clarity in Microsoft.IdentityModel.Tokens

src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectGrantTypes.cs

@@ -29,27 +29,27 @@ public static class OpenIdConnectGrantTypes
         public const string ClientCredentials = "client_credentials";
 
         /// <summary>
-        /// Indicates the 'saml2-bearer' grant type. See <see href="https://datatracker.ietf.org/doc/html/rfc7522"/>.
+        /// Indicates the 'saml2-bearer' grant type. See: <see href="https://datatracker.ietf.org/doc/html/rfc7522"/>.
         /// </summary>
         public const string Saml2Bearer = "urn:ietf:params:oauth:grant-type:saml2-bearer";
 
         /// <summary>
-        /// Indicates the 'jwt-bearer' grant type. See <see href="https://datatracker.ietf.org/doc/html/rfc7523"/>.
+        /// Indicates the 'jwt-bearer' grant type. See: <see href="https://datatracker.ietf.org/doc/html/rfc7523"/>.
         /// </summary>
         public const string JwtBearer = "urn:ietf:params:oauth:grant-type:jwt-bearer";
 
         /// <summary>
-        /// Indicates the 'device_code' grant type. See <see href="https://datatracker.ietf.org/doc/html/rfc8628"/>.
+        /// Indicates the 'device_code' grant type. See: <see href="https://datatracker.ietf.org/doc/html/rfc8628"/>.
         /// </summary>
         public const string DeviceCode = "urn:ietf:params:oauth:grant-type:device_code";
 
         /// <summary>
-        /// Indicates the 'token-exchange' grant type. See <see href="https://datatracker.ietf.org/doc/html/rfc8693"/>.
+        /// Indicates the 'token-exchange' grant type. See: <see href="https://datatracker.ietf.org/doc/html/rfc8693"/>.
         /// </summary>
         public const string TokenExchange = "urn:ietf:params:oauth:grant-type:token-exchange";
 
         /// <summary>
-        /// Indicates the 'ciba' grant type. See <see href="https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html"/>.
+        /// Indicates the 'ciba' grant type. See: <see href="https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html"/>.
         /// </summary>
         public const string Ciba = "urn:openid:params:grant-type:ciba";
     }

src/Microsoft.IdentityModel.Tokens/AsymmetricAdapter.cs

@@ -22,7 +22,7 @@ namespace Microsoft.IdentityModel.Tokens
     delegate bool VerifyUsingOffsetDelegate(byte[] bytes, int offset, int count, byte[] signature);
 
     /// <summary>
-    /// This adapter abstracts the 'RSA' differences between versions of .Net targets.
+    /// This adapter abstracts the 'RSA' differences between versions of .NET targets.
     /// </summary>
     internal class AsymmetricAdapter : IDisposable
     {
@@ -102,7 +102,7 @@ internal static byte[] DecryptFunctionNotFound(byte[] _)
         }
 
         /// <summary>
-        /// Calls <see cref="Dispose(bool)"/> and <see cref="GC.SuppressFinalize"/>
+        /// Calls <see cref="Dispose(bool)"/> and <see cref="GC.SuppressFinalize"/>.
         /// </summary>
         public void Dispose()
         {
@@ -460,7 +460,6 @@ private bool VerifyWithRsaCryptoServiceProviderProxyUsingOffset(byte[] bytes, in
         {
             return RsaCryptoServiceProviderProxy.VerifyDataWithLength(bytes, offset, length, HashAlgorithm, HashAlgorithmName, signature);
         }
-
 #endif
 #endregion
 

src/Microsoft.IdentityModel.Tokens/AsymmetricSecurityKey.cs

@@ -4,12 +4,12 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Base class for a Security Key that contains Asymmetric key material.
+    /// Base class for a <see cref="SecurityKey"/> that contains Asymmetric key material.
     /// </summary>
     public abstract class AsymmetricSecurityKey : SecurityKey
     {
         /// <summary>
-        /// Default constructor
+        /// Initializes a new instance of the <see cref="AsymmetricSecurityKey"/> class.
         /// </summary>
         public AsymmetricSecurityKey()
         {
@@ -30,7 +30,7 @@ internal AsymmetricSecurityKey(SecurityKey key)
         /// <summary>
         /// Gets the status 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>
+        /// <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>
         public abstract PrivateKeyStatus PrivateKeyStatus { get; }
     }
 

src/Microsoft.IdentityModel.Tokens/AsymmetricSignatureProvider.cs

@@ -20,7 +20,7 @@ public class AsymmetricSignatureProvider : SignatureProvider
         private Dictionary<string, int> _minimumAsymmetricKeySizeInBitsForVerifyingMap;
 
         /// <summary>
-        /// Mapping from algorithm to minimum <see cref="AsymmetricSecurityKey"/>.KeySize when creating signatures.
+        /// Mapping from algorithm to minimum <see cref="SecurityKey.KeySize"/> when creating signatures.
         /// </summary>
         public static readonly Dictionary<string, int> DefaultMinimumAsymmetricKeySizeInBitsForSigningMap = new Dictionary<string, int>()
         {
@@ -45,7 +45,7 @@ public class AsymmetricSignatureProvider : SignatureProvider
         };
 
         /// <summary>
-        /// Mapping from algorithm to minimum <see cref="AsymmetricSecurityKey"/>.KeySize when verifying signatures.
+        /// Mapping from algorithm to minimum <see cref="SecurityKey.KeySize"/> when verifying signatures.
         /// </summary>
         public static readonly Dictionary<string, int> DefaultMinimumAsymmetricKeySizeInBitsForVerifyingMap = new Dictionary<string, int>()
         {
@@ -92,26 +92,18 @@ public AsymmetricSignatureProvider(SecurityKey key, string algorithm)
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="AsymmetricSignatureProvider"/> class used to create and verify signatures.
+        /// Initializes a new instance of the <see cref="AsymmetricSignatureProvider"/> class used for creating and verifying signatures.
         /// </summary>
         /// <param name="key">The <see cref="SecurityKey"/> that will be used for signature operations.</param>
         /// <param name="algorithm">The signature algorithm to apply.</param>
-        /// <param name="willCreateSignatures">If this <see cref="AsymmetricSignatureProvider"/> is required to create signatures then set this to true.</param>
-        /// <para>
-        /// Creating signatures requires that the <see cref="SecurityKey"/> has access to a private key.
-        /// Verifying signatures (the default), does not require access to the private key.
-        /// </para>
-        /// <exception cref="ArgumentNullException"><paramref name="key"/>is null.</exception>
-        /// <exception cref="ArgumentNullException"><paramref name="algorithm"/>is null or empty.</exception>
-        /// <exception cref="InvalidOperationException"><paramref name="willCreateSignatures"/>is true and there is no private key.</exception>
-        /// <exception cref="NotSupportedException">If <see cref="SecurityKey"/> and algorithm pair are not supported.</exception>
-        /// <exception cref="ArgumentOutOfRangeException">
-        /// willCreateSignatures is true and <see cref="SecurityKey"/>.KeySize is less than the size corresponding to the given algorithm in <see cref="AsymmetricSignatureProvider.MinimumAsymmetricKeySizeInBitsForSigningMap"/>.
-        /// </exception>
-        /// <exception cref="ArgumentOutOfRangeException">
-        /// <see cref="SecurityKey"/>.KeySize is less than the size corresponding to the algorithm in <see cref="AsymmetricSignatureProvider.MinimumAsymmetricKeySizeInBitsForVerifyingMap"/>. Note: this is always checked.
-        /// </exception>
-        /// <exception cref="InvalidOperationException">If the runtime is unable to create a suitable cryptographic provider.</exception>
+        /// <param name="willCreateSignatures">If true, the provider will be used for creating signatures; otherwise, it will be used for verifying 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="InvalidOperationException">Thrown if <paramref name="willCreateSignatures"/> is true and there is no private key available.</exception>
+        /// <exception cref="NotSupportedException">Thrown if the <see cref="SecurityKey"/> and algorithm pair are not supported.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="willCreateSignatures"/> is true and <see cref="SecurityKey.KeySize"/> is less than the required size for signing.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown if <see cref="SecurityKey.KeySize"/> is less than the required size for verifying signatures.</exception>
+        /// <exception cref="InvalidOperationException">Thrown if the runtime is unable to create a suitable cryptographic provider.</exception>
         public AsymmetricSignatureProvider(SecurityKey key, string algorithm, bool willCreateSignatures)
             : base(key, algorithm)
         {
@@ -134,15 +126,15 @@ public AsymmetricSignatureProvider(SecurityKey key, string algorithm, bool willC
         }
 
         /// <summary>
-        /// Gets the mapping from algorithm to the minimum <see cref="AsymmetricSecurityKey"/>.KeySize for creating signatures.
+        /// Gets the mapping from algorithm to the minimum <see cref="SecurityKey.KeySize"/> for creating signatures.
         /// </summary>
         public IReadOnlyDictionary<string, int> MinimumAsymmetricKeySizeInBitsForSigningMap
         {
             get => _minimumAsymmetricKeySizeInBitsForSigningMap;
         }
 
         /// <summary>
-        /// Gets the mapping from algorithm to the minimum <see cref="AsymmetricSecurityKey"/>.KeySize for verifying signatures.
+        /// Gets the mapping from algorithm to the minimum <see cref="SecurityKey.KeySize"/> for verifying signatures.
         /// </summary>
         public IReadOnlyDictionary<string, int> MinimumAsymmetricKeySizeInBitsForVerifyingMap
         {
@@ -167,8 +159,8 @@ private static PrivateKeyStatus FoundPrivateKey(SecurityKey key)
         /// </summary>
         /// <param name="algorithm">The SignatureAlgorithm in use.</param>
         /// <returns>The <see cref="HashAlgorithmName"/> to use.</returns>
-        /// <exception cref="ArgumentNullException">if <paramref name="algorithm"/> is null or whitespace.</exception>
-        /// <exception cref="ArgumentOutOfRangeException">if <paramref name="algorithm"/> is not supported.</exception>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="algorithm"/> is null or whitespace.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="algorithm"/> is not supported.</exception>
         protected virtual HashAlgorithmName GetHashAlgorithmName(string algorithm)
         {
             if (string.IsNullOrWhiteSpace(algorithm))
@@ -233,9 +225,8 @@ public override bool Sign(ReadOnlySpan<byte> input, Span<byte> signature, out in
         /// </summary>
         /// <param name="input">The bytes to be signed.</param>
         /// <returns>A signature over the input.</returns>
-        /// <exception cref="ArgumentNullException">if <paramref name="input"/> is null.</exception>
-        /// <exception cref="ArgumentNullException">if <paramref name="input"/>.Length == 0.</exception>
-        /// <exception cref="ObjectDisposedException">If <see cref="AsymmetricSignatureProvider.Dispose(bool)"/> has been called. </exception>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="input"/> is null or has length of 0.</exception>
+        /// <exception cref="ObjectDisposedException">Thrown If <see cref="AsymmetricSignatureProvider.Dispose(bool)"/> has been called.</exception>
         /// <remarks>Sign is thread safe.</remarks>
         public override byte[] Sign(byte[] input)
         {
@@ -304,10 +295,9 @@ public override byte[] Sign(byte[] input, int offset, int count)
         /// <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>
-        /// <exception cref="ArgumentNullException">if <paramref name="key"/>is null.</exception>
-        /// <exception cref="ArgumentNullException">if <paramref name="algorithm"/>is null or empty.</exception>
-        /// <exception cref="ArgumentOutOfRangeException">if <paramref name="key"/>.KeySize is less than the minimum
-        /// acceptable size.</exception>
+        /// <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>
         /// <remarks>
         /// <seealso cref="MinimumAsymmetricKeySizeInBitsForSigningMap"/> for minimum signing sizes.
         /// <seealso cref="MinimumAsymmetricKeySizeInBitsForVerifyingMap"/> for minimum verifying sizes.
@@ -359,9 +349,9 @@ public virtual void ValidateAsymmetricSecurityKeySize(SecurityKey key, string al
         /// <param name="input">The bytes to generate the signature over.</param>
         /// <param name="signature">The value to verify against.</param>
         /// <returns>true if signature matches, false otherwise.</returns>
-        /// <exception cref="ArgumentNullException"><paramref name="input"/> is null or has length == 0.</exception>
-        /// <exception cref="ArgumentNullException"><paramref name="signature"/> is null or has length == 0.</exception>
-        /// <exception cref="ObjectDisposedException">If <see cref="AsymmetricSignatureProvider.Dispose(bool)"/> has been called. </exception>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="input"/> is null or has length of 0.</exception>
+        /// <exception cref="ArgumentNullException">Thrown if <paramref name="signature"/> is null or has length of 0.</exception>
+        /// <exception cref="ObjectDisposedException">Thrown if <see cref="AsymmetricSignatureProvider.Dispose(bool)"/> has been called.</exception>
         /// <remarks>Verify is thread safe.</remarks>
         public override bool Verify(byte[] input, byte[] signature)
         {