Documentation consistency for PQC types

Author: vcsjones

src/libraries/Common/src/System/Security/Cryptography/MLDsa.cs

@@ -14,10 +14,15 @@ namespace System.Security.Cryptography
     ///   Represents an ML-DSA key.
     /// </summary>
     /// <remarks>
-    ///   Developers are encouraged to program against the <see cref="MLDsa"/> base class,
-    ///   rather than any specific derived class.
-    ///   The derived classes are intended for interop with the underlying system
-    ///   cryptographic libraries.
+    ///   <para>
+    ///     This algorithm is specified by FIPS-204.
+    ///   </para>
+    ///   <para>
+    ///     Developers are encouraged to program against the <see cref="MLDsa"/> base class,
+    ///     rather than any specific derived class.
+    ///     The derived classes are intended for interop with the underlying system
+    ///     cryptographic libraries.
+    ///   </para>
     /// </remarks>
     [Experimental(Experimentals.PostQuantumCryptographyDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
     public abstract partial class MLDsa : IDisposable
@@ -39,6 +44,9 @@ public abstract partial class MLDsa : IDisposable
         /// <summary>
         ///   Gets the specific ML-DSA algorithm for this key.
         /// </summary>
+        /// <value>
+        ///   The specific ML-DSA algorithm for this key.
+        /// </value>
         public MLDsaAlgorithm Algorithm { get; }
         private bool _disposed;
 
@@ -48,6 +56,9 @@ public abstract partial class MLDsa : IDisposable
         /// <param name="algorithm">
         ///   The specific ML-DSA algorithm for this key.
         /// </param>
+        /// <exception cref="ArgumentNullException">
+        ///   <paramref name="algorithm" /> is <see langword="null" />.
+        /// </exception>
         protected MLDsa(MLDsaAlgorithm algorithm)
         {
             ArgumentNullException.ThrowIfNull(algorithm);
@@ -79,7 +90,7 @@ public void Dispose()
         }
 
         /// <summary>
-        ///   Sign the specified data, writing the signature into the provided buffer.
+        ///   Signs the specified data, writing the signature into the provided buffer.
         /// </summary>
         /// <param name="data">
         ///   The data to sign.

src/libraries/Common/src/System/Security/Cryptography/MLKem.cs

@@ -40,10 +40,10 @@ public abstract partial class MLKem : IDisposable
         public static bool IsSupported => MLKemImplementation.IsSupported;
 
         /// <summary>
-        ///   Gets the algorithm of the current instance.
+        ///   Gets the specific ML-KEM algorithm for this key.
         /// </summary>
         /// <value>
-        ///   A value representing the ML-KEM algorithm.
+        ///   The specific ML-KEM algorithm for this key.
         /// </value>
         public MLKemAlgorithm Algorithm { get; }
 
@@ -183,6 +183,14 @@ public void Encapsulate(out byte[] ciphertext, out byte[] sharedSecret)
         /// <param name="sharedSecret">
         ///   The buffer to receive the shared secret.
         /// </param>
+        /// <remarks>
+        ///   Decapsulation can only decapsulate a shared secret created with the the decapsulation key's
+        ///   corresponding encapsulation key. If a different key is used, ML-KEM performs implicit rejection.
+        ///   Implicit rejection means an error will not be returned. Instead, the shared secret will be a
+        ///   deterministic but incorrect result.
+        ///   Detecting incorrect key use is a concern for consumers of the ML-KEM algorithm.
+        ///   For more information, see FIPS 203, Section 6.3.
+        /// </remarks>
         /// <exception cref="CryptographicException">
         ///   An error occurred during decapsulation.
         /// </exception>
@@ -219,6 +227,14 @@ public void Decapsulate(ReadOnlySpan<byte> ciphertext, Span<byte> sharedSecret)
         /// <returns>
         ///   The shared secret.
         /// </returns>
+        /// <remarks>
+        ///   Decapsulation can only decapsulate a shared secret created with the the decapsulation key's
+        ///   corresponding encapsulation key. If a different key is used, ML-KEM performs implicit rejection.
+        ///   Implicit rejection means an error will not be returned. Instead, the shared secret will be a
+        ///   deterministic but incorrect result.
+        ///   Detecting incorrect key use is a concern for consumers of the ML-KEM algorithm.
+        ///   For more information, see FIPS 203, Section 6.3.
+        /// </remarks>
         /// <exception cref="CryptographicException">
         ///   An error occurred during decapsulation.
         /// </exception>

src/libraries/Common/src/System/Security/Cryptography/SlhDsa.cs

@@ -14,10 +14,15 @@ namespace System.Security.Cryptography
     ///   Represents an SLH-DSA key.
     /// </summary>
     /// <remarks>
-    ///   Developers are encouraged to program against the <c>SlhDsa</c> base class,
-    ///   rather than any specific derived class.
-    ///   The derived classes are intended for interop with the underlying system
-    ///   cryptographic libraries.
+    ///   <para>
+    ///     This algorithm is specified by FIPS-205.
+    ///   </para>
+    ///   <para>
+    ///     Developers are encouraged to program against the <see cref="SlhDsa"/> base class,
+    ///     rather than any specific derived class.
+    ///     The derived classes are intended for interop with the underlying system
+    ///     cryptographic libraries.
+    ///   </para>
     /// </remarks>
     [Experimental(Experimentals.PostQuantumCryptographyDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
     public abstract partial class SlhDsa : IDisposable
@@ -62,9 +67,6 @@ protected SlhDsa(SlhDsaAlgorithm algorithm)
             Algorithm = algorithm;
         }
 
-        /// <summary>
-        ///   Throws <see cref="ObjectDisposedException" /> if the current instance is disposed.
-        /// </summary>
         private protected void ThrowIfDisposed() => ObjectDisposedException.ThrowIf(_disposed, typeof(SlhDsa));
 
         /// <summary>