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

…2678)

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

* Fix typo

* Apply suggestions from review

* Apply suggestions from review

* Fix missing parenthesis

* Fix unknown paramref

---------

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

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

@@ -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)
         {
@@ -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)
         {

src/Microsoft.IdentityModel.Tokens/Base64UrlEncoder.cs

@@ -12,7 +12,7 @@
 namespace Microsoft.IdentityModel.Tokens
 {
     /// <summary>
-    /// Encodes and Decodes strings as Base64Url encoding.
+    /// Encodes and Decodes strings as base64url encoding.
     /// </summary>
     public static class Base64UrlEncoder
     {
@@ -23,13 +23,13 @@ public static class Base64UrlEncoder
         private const char base64UrlCharacter63 = '_';
 
         /// <summary>
-        /// The following functions perform base64url encoding which differs from regular base64 encoding as follows
-        /// * padding is skipped so the pad character '=' doesn't have to be percent encoded
-        /// * the 62nd and 63rd regular base64 encoding characters ('+' and '/') are replace with ('-' and '_')
-        /// The changes make the encoding alphabet file and URL safe.
+        /// Performs base64url encoding, which differs from regular base64 encoding as follows:
+        /// * Padding is skipped so the pad character '=' doesn't have to be percent encoded.
+        /// * The 62nd and 63rd regular base64 encoding characters ('+' and '/') are replaced with ('-' and '_').
+        /// This makes the encoding alphabet URL safe.
         /// </summary>
-        /// <param name="arg">string to encode.</param>
-        /// <returns>Base64Url encoding of the UTF8 bytes.</returns>
+        /// <param name="arg">The string to encode.</param>
+        /// <returns>The base64url encoding of the UTF8 bytes.</returns>
         public static string Encode(string arg)
         {
             _ = arg ?? throw LogHelper.LogArgumentNullException(nameof(arg));
@@ -38,12 +38,12 @@ public static string Encode(string arg)
         }
 
         /// <summary>
-        /// Converts a subset of an array of 8-bit unsigned integers to its equivalent string representation which is encoded with base-64-url digits.
+        /// Converts a subset of an array of 8-bit unsigned integers to its equivalent string representation encoded with base64url digits.
         /// </summary>
         /// <param name="inArray">An array of 8-bit unsigned integers.</param>
-        /// <returns>The string representation in base 64 url encoding of length elements of inArray, starting at position offset.</returns>
-        /// <exception cref="ArgumentNullException">'inArray' is null.</exception>
-        /// <exception cref="ArgumentOutOfRangeException">offset or length is negative OR offset plus length is greater than the length of inArray.</exception>
+        /// <returns>The base64url encoded string representation of the elements in inArray.</returns>
+        /// <exception cref="ArgumentNullException">Thrown if inArray is null.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown if offset or length is negative, or if offset plus length is greater than the length of inArray.</exception>
         public static string Encode(byte[] inArray)
         {
             _ = inArray ?? throw LogHelper.LogArgumentNullException(nameof(inArray));
@@ -52,15 +52,15 @@ public static string Encode(byte[] inArray)
         }
 
         /// <summary>
-        /// Converts a subset of an array of 8-bit unsigned integers to its equivalent string representation which is encoded with base-64-url digits. Parameters specify
-        /// the subset as an offset in the input array, and the number of elements in the array to convert.
+        /// Converts a subset of an array of 8-bit unsigned integers to its equivalent string representation encoded with base64url digits.
+        /// Parameters specify the subset as an offset in the input array and the number of elements in the array to convert.
         /// </summary>
         /// <param name="inArray">An array of 8-bit unsigned integers.</param>
-        /// <param name="length">An offset in inArray.</param>
-        /// <param name="offset">The number of elements of inArray to convert.</param>
-        /// <returns>The string representation in base 64 url encoding of length elements of inArray, starting at position offset.</returns>
-        /// <exception cref="ArgumentNullException">'inArray' is null.</exception>
-        /// <exception cref="ArgumentOutOfRangeException">offset or length is negative OR offset plus length is greater than the length of inArray.</exception>
+        /// <param name="offset">An offset in inArray.</param>
+        /// <param name="length">The number of elements of inArray to convert.</param>
+        /// <returns>The base64url encoded string representation of length elements of inArray, starting at position offset.</returns>
+        /// <exception cref="ArgumentNullException">Thrown if inArray is null.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown if offset or length is negative, or if offset plus length is greater than the length of inArray.</exception>
         public static string Encode(byte[] inArray, int offset, int length)
         {
             _ = inArray ?? throw LogHelper.LogArgumentNullException(nameof(inArray));
@@ -105,12 +105,11 @@ public static string Encode(byte[] inArray, int offset, int length)
         }
 
         /// <summary>
-        /// Populates a <see cref="ReadOnlySpan{T}"/>Converts a <see cref="Span{T}"/> encoded with base-64-url digits. Parameters specify
-        /// the subset as an offset in the input array, and the number of elements in the array to convert.
+        /// Populates a <see cref="Span{T}"/> with the base64url encoded representation of a <see cref="ReadOnlySpan{T}"/> of bytes.
         /// </summary>
-        /// <param name="inArray">A span of bytes.</param>
-        /// <param name="output">output for encoding.</param>
-        /// <returns>The number of chars written to the output.</returns>
+        /// <param name="inArray">A read-only span of bytes to encode.</param>
+        /// <param name="output">The span of characters to write the encoded output.</param>
+        /// <returns>The number of characters written to the output span.</returns>
         public static int Encode(ReadOnlySpan<byte> inArray, Span<char> output)
         {
             int lengthmod3 = inArray.Length % 3;
@@ -167,9 +166,10 @@ public static int Encode(ReadOnlySpan<byte> inArray, Span<char> output)
         }
 
         /// <summary>
-        /// Converts the specified string, base-64-url encoded to utf8 bytes.</summary>
-        /// <param name="str">base64Url encoded string.</param>
-        /// <returns>UTF8 bytes.</returns>
+        /// Converts the specified base64url encoded string to UTF-8 bytes.
+        /// </summary>
+        /// <param name="str">The base64url encoded string.</param>
+        /// <returns>The UTF-8 bytes.</returns>
         public static byte[] DecodeBytes(string str)
         {
             _ = str ?? throw LogHelper.LogExceptionMessage(new ArgumentNullException(nameof(str)));
@@ -357,10 +357,10 @@ private static void Decode(ReadOnlySpan<char> strSpan, Span<byte> output, bool n
 #endif
 
         /// <summary>
-        /// Decodes the string from Base64UrlEncoded to UTF8.
+        /// Decodes the specified base64url encoded string to UTF-8.
         /// </summary>
-        /// <param name="arg">string to decode.</param>
-        /// <returns>UTF8 string.</returns>
+        /// <param name="arg">The base64url encoded string to decode.</param>
+        /// <returns>The UTF-8 decoded string.</returns>
         public static string Decode(string arg)
         {
             return Encoding.UTF8.GetString(DecodeBytes(arg));