Document SafeEvpPKeyHandle (#2870)

* Document SafeEvpPKeyHandle

* Apply suggestions from code review

Co-Authored-By: Ron Petrusha <[email protected]>

Author: bartonjs

xml/System.Security.Cryptography/SafeEvpPKeyHandle.xml

@@ -17,8 +17,16 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Represents the <see langword="EVP_PKEY*"/> pointer type from OpenSSL.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+ Before using <xref:System.Security.Cryptography.SafeEvpPKeyHandle> to perform interop with OpenSSL a caller must ensure that the version of OpenSSL they are calling is the same as the version the .NET runtime is calling, and not a side-by-side version. The version of OpenSSL that the runtime is calling can be determined by <xref:System.Security.Cryptography.SafeEvpPKeyHandle.OpenSslVersion>.
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -41,9 +49,9 @@
         <Parameter Name="ownsHandle" Type="System.Boolean" />
       </Parameters>
       <Docs>
-        <param name="handle">To be added.</param>
-        <param name="ownsHandle">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="handle">The handle value to represent.</param>
+        <param name="ownsHandle"><see langword="true" /> to reliably let <see cref="T:System.Security.Cryptography.SafeEvpPKeyHandle" /> release the handle during the finalization phase; otherwise, <see langword="false" /> (not recommended).</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.SafeEvpPKeyHandle" /> class with the specified handle value.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -67,9 +75,11 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Creates another instance of this type which has an independent lifetime but tracks the same resource.</summary>
+        <returns>Another instance of this type which has an independent lifetime but tracks the same resource.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.InvalidOperationException">This handle is invalid.</exception>
+        <altmember cref="P:System.Security.Cryptography.SafeEvpPKeyHandle.IsInvalid" />
       </Docs>
     </Member>
     <Member MemberName="IsInvalid">
@@ -91,8 +101,8 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets a value indicating whether the handle value is invalid.</summary>
+        <value><see langword="true" /> if the handle value is invalid; otherwise, <see langword="false" />.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -112,9 +122,21 @@
         <ReturnType>System.Int64</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets a value representing the version number as reported by the loaded version of OpenSSL.</summary>
+        <value>A value representing the version number as reported by the loaded version of OpenSSL.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+ Before using <xref:System.Security.Cryptography.SafeEvpPKeyHandle> to perform interop with OpenSSL a caller must ensure that the version of OpenSSL they are calling is the same as the version the .NET runtime is calling, and not a side-by-side version.
+
+ For OpenSSL 1.1.0 and newer, this value is reported from the `OpenSSL_version_num()` function. When an older version of OpenSSL is in use, this value is reported from the `SSLeay()` function.
+
+ Callers are encouraged to only perform an equality check with this value.
+
+ ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="ReleaseHandle">
@@ -137,10 +159,10 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Executes the code required to free the handle.</summary>
+        <returns><see langword="true"/> in all cases.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>