Document Pkcs9LocalKeyId (dotnet#2934)

bartonjs · Ron Petrusha · commit 2053bbdce5da · 2019-08-06T16:45:46.000Z
* Document Pkcs9LocalKeyId

* Apply suggestions from code review
diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs9LocalKeyId.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs9LocalKeyId.xml
@@ -15,8 +15,16 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Represents the LocalKeyId attribute from PKCS#9.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+The primary use of the LocalKeyId attribute is to associate an X.509 Public Key Certificate and its matching asymmetric private key in a PKCS#12 PFX file.
+
+]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -33,7 +41,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs.Pkcs9LocalKeyId"/> class with an empty key identifier value.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -54,9 +62,10 @@
         <Parameter Name="keyId" Type="System.Byte[]" />
       </Parameters>
       <Docs>
-        <param name="keyId">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="keyId">A byte array containing the key identifier.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs.Pkcs9LocalKeyId"/> class with a key identifier specified by a byte array.</summary>
         <remarks>To be added.</remarks>
+        <altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs9LocalKeyId.KeyId"/>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -76,9 +85,10 @@
         <Parameter Name="keyId" Type="System.ReadOnlySpan&lt;System.Byte&gt;" />
       </Parameters>
       <Docs>
-        <param name="keyId">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="keyId">A byte array containing the key identifier.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.Pkcs.Pkcs9LocalKeyId"/> class with a key identifier specified by a byte span.</summary>
         <remarks>To be added.</remarks>
+        <altmember cref="P:System.Security.Cryptography.Pkcs.Pkcs9LocalKeyId.KeyId"/>
       </Docs>
     </Member>
     <Member MemberName="KeyId">
@@ -98,10 +108,18 @@
         <ReturnType>System.ReadOnlyMemory&lt;System.Byte&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets a memory value containing the key identifier from this attribute.</summary>
+        <value>A memory value containing the key identifier from this attribute.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+Local key identifiers have no inherent semantic meaning to a PKCS#12 PFX. A private key is considered to be associated with the a certificate if both values have a LocalKeyId attribute and the attributes' KeyId values are equal on a byte-by-byte basis.
+
+]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>
