From 1aa6a7b3b086ca2d768069a6ae85376f282e7b1d Mon Sep 17 00:00:00 2001
From: carlossanlop <calope@microsoft.com>
Date: Thu, 8 Aug 2019 10:15:41 -0700
Subject: [PATCH 1/3] Document 2 APIs in System.Security.Cryptography.DSACng

---
 xml/System.Security.Cryptography/DSACng.xml | 31 ++++++++++-----------
 1 file changed, 14 insertions(+), 17 deletions(-)

diff --git a/xml/System.Security.Cryptography/DSACng.xml b/xml/System.Security.Cryptography/DSACng.xml
index 3bc9fb7f307..dbb4600ee60 100644
--- a/xml/System.Security.Cryptography/DSACng.xml
+++ b/xml/System.Security.Cryptography/DSACng.xml
@@ -171,10 +171,8 @@
         <summary>Creates the digital signature for the specified data.</summary>
         <returns>The digital signature for the specified data.</returns>
         <remarks>To be added.</remarks>
-        <exception cref="T:System.ArgumentNullException">
-          <paramref name="rgbHash" /> is <see langword="null" />.</exception>
-        <exception cref="T:System.PlatformNotSupportedException">
-          <paramref name="rgbHash" /> is shorter in length than the Q value of the DSA key .</exception>
+        <exception cref="T:System.ArgumentNullException"><paramref name="rgbHash" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.PlatformNotSupportedException"><paramref name="rgbHash" /> is shorter in length than the Q value of the DSA key .</exception>
       </Docs>
     </Member>
     <Member MemberName="Dispose">
@@ -485,11 +483,11 @@
         <Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="2" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="hash">To be added.</param>
-        <param name="destination">To be added.</param>
-        <param name="bytesWritten">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="hash">A read-only span of bytes containing the data to be signed.</param>
+        <param name="destination">The buffer where the digital signature is to be written.</param>
+        <param name="bytesWritten">When this method returns, the number of bytes that were written in <paramref name="destination" />.</param>
+        <summary>Tries to create the digital signature for the specified data.</summary>
+        <returns><see langword="true" /> if the digital signature was created successfully; <see langword="false" /> if the <paramref name="destination" /> buffer was too small.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -561,16 +559,14 @@
         <param name="rgbHash">The signed data.</param>
         <param name="rgbSignature">The digital signature to be verified.</param>
         <summary>Verifies if the specified digital signature matches the specified data.</summary>
-        <returns>
-          <see langword="true" /> if <paramref name="rgbSignature" /> matches the signature computed using the specified data; otherwise, <see langword="false" />.</returns>
+        <returns><see langword="true" /> if <paramref name="rgbSignature" /> matches the signature computed using the specified data; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">The <paramref name="rgbHash" /> parameter is <see langword="null" />.  
   
  -or-  
   
  The <paramref name="rgbSignature" /> parameter is <see langword="null" />.</exception>
-        <exception cref="T:System.PlatformNotSupportedException">
-          <paramref name="rgbHash" /> is shorter in length than the Q value of the DSA key .</exception>
+        <exception cref="T:System.PlatformNotSupportedException"><paramref name="rgbHash" /> is shorter in length than the Q value of the DSA key.</exception>
       </Docs>
     </Member>
     <Member MemberName="VerifySignature">
@@ -596,11 +592,12 @@
         <Parameter Name="signature" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="1" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="hash">To be added.</param>
-        <param name="signature">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="hash">A read-only span of bytes containing the signed data.</param>
+        <param name="signature">A read-only span of bytes containing the signature to be verified.</param>
+        <summary>Verifies if the specified digital signature matches the specified data.</summary>
+        <returns><see langword="true" /> if <paramref name="rgbSignature" /> matches the signature computed using the specified data; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.PlatformNotSupportedException"><paramref name="rgbHash" /> is shorter in length than the Q value of the DSA key.</exception>
       </Docs>
     </Member>
   </Members>

From d8b41516e6bae3b9ffb8a097dff6a61b96695efc Mon Sep 17 00:00:00 2001
From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com>
Date: Thu, 8 Aug 2019 13:00:00 -0700
Subject: [PATCH 2/3] suggestions

Co-Authored-By: Eric StJohn <ericstj@microsoft.com>
Co-Authored-By: Ron Petrusha <ronpet@microsoft.com>
---
 xml/System.Security.Cryptography/DSACng.xml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/xml/System.Security.Cryptography/DSACng.xml b/xml/System.Security.Cryptography/DSACng.xml
index dbb4600ee60..1d781fdc840 100644
--- a/xml/System.Security.Cryptography/DSACng.xml
+++ b/xml/System.Security.Cryptography/DSACng.xml
@@ -483,7 +483,7 @@
         <Parameter Name="bytesWritten" Type="System.Int32" RefType="out" Index="2" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="hash">A read-only span of bytes containing the data to be signed.</param>
+        <param name="hash">A read-only span of bytes containing a hash of the data to be signed.</param>
         <param name="destination">The buffer where the digital signature is to be written.</param>
         <param name="bytesWritten">When this method returns, the number of bytes that were written in <paramref name="destination" />.</param>
         <summary>Tries to create the digital signature for the specified data.</summary>
@@ -595,10 +595,10 @@
         <param name="hash">A read-only span of bytes containing the signed data.</param>
         <param name="signature">A read-only span of bytes containing the signature to be verified.</param>
         <summary>Verifies if the specified digital signature matches the specified data.</summary>
-        <returns><see langword="true" /> if <paramref name="rgbSignature" /> matches the signature computed using the specified data; otherwise, <see langword="false" />.</returns>
+        <returns><see langword="true" /> if <paramref name="signature" /> matches the signature computed using the specified data; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.PlatformNotSupportedException"><paramref name="rgbHash" /> is shorter in length than the Q value of the DSA key.</exception>
       </Docs>
     </Member>
   </Members>
-</Type>
\ No newline at end of file
+</Type>

From 8f36009245dabcb24811cb325a5943149b46d964 Mon Sep 17 00:00:00 2001
From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com>
Date: Thu, 8 Aug 2019 14:28:47 -0700
Subject: [PATCH 3/3] suggestion by mairaw

Co-Authored-By: Maira Wenzel <mairaw@microsoft.com>
---
 xml/System.Security.Cryptography/DSACng.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/xml/System.Security.Cryptography/DSACng.xml b/xml/System.Security.Cryptography/DSACng.xml
index 1d781fdc840..dd5d9ccf675 100644
--- a/xml/System.Security.Cryptography/DSACng.xml
+++ b/xml/System.Security.Cryptography/DSACng.xml
@@ -597,7 +597,7 @@
         <summary>Verifies if the specified digital signature matches the specified data.</summary>
         <returns><see langword="true" /> if <paramref name="signature" /> matches the signature computed using the specified data; otherwise, <see langword="false" />.</returns>
         <remarks>To be added.</remarks>
-        <exception cref="T:System.PlatformNotSupportedException"><paramref name="rgbHash" /> is shorter in length than the Q value of the DSA key.</exception>
+        <exception cref="T:System.PlatformNotSupportedException"><paramref name="hash" /> is shorter in length than the Q value of the DSA key.</exception>
       </Docs>
     </Member>
   </Members>