Documented IPinnable, MemoryHandle (dotnet#736)

* Documented IPinnable, MemoryHandle

* Fixed badly formatted XML.

* Addressed review comments

Author: Ron Petrusha

xml/System.Buffers/IPinnable.xml

@@ -14,8 +14,16 @@
   </AssemblyInfo>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Provides a mechanism for pinning and unpinning objects to prevent the garbage collector from moving them.</summary>
+    <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+
+The <xref:System.Buffers.MemoryManager%601> class implements the `IPinnable` interface.
+
+       ]]></format>        
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="Pin">
@@ -40,10 +48,21 @@
         <Parameter Name="elementIndex" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <param name="elementIndex">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="elementIndex">The offset to the element within the memory buffer to which the returned <see cref="T:System.Buffers.MemoryHandle" /> points.</param>
+        <summary>Pins a block of memory.</summary>
+        <returns>A handle to the block of memory.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+
+A developer can access an object that implements the <xref:System.Buffers.IPinnable> interface without pinning it only through managed APIs. Pinning is required for access by unmanaged APIs. 
+
+Call this method to indicate that the <xref:System.Buffers.IPinnable> object cannot be moved by the garbage collector so that the address of the pinned object can be used.
+
+
+       ]]></format>        
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Unpin">
@@ -66,8 +85,17 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <summary>Frees a block of pinned memory.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+
+Call this method to indicate that the <xref:System.Buffers.IPinnable> object no longer needs to be pinned, and that the garbage collector can now move the object.
+
+
+       ]]></format>        
+        </remarks>
       </Docs>
     </Member>
   </Members>

xml/System.Buffers/MemoryHandle.xml

@@ -21,8 +21,21 @@
     </Interface>
   </Interfaces>
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Provides a memory handle for a block of memory.</summary>
+    <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+
+A `MemoryHandle` instance represents a handle to a pinned block of memory. It is returned by the following methods:
+
+- <xref:System.Buffers.IPinnable.Pin%2A?displayProperty=nameWithType>.
+- <xref:System.Memory%601.Pin%2A?displayProperty=nameWithType>
+- <xref:System.ReadOnlyMemory%601.Pin%2A?displayProperty=nameWithType>.
+- <xref:System.Buffers.MemoryManager%601.Pin%2A?displayProperty=<nameWithType>
+
+ ]]></format>    
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -49,10 +62,10 @@
         <Parameter Name="pinnable" Type="System.Buffers.IPinnable" />
       </Parameters>
       <Docs>
-        <param name="pointer">To be added.</param>
-        <param name="handle">To be added.</param>
-        <param name="pinnable">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="pointer">A pointer to memory..</param>
+        <param name="handle">A handle used to pin array buffers.</param>
+        <param name="pinnable">A reference to a manually managed object, or <see langword="default" /> if there is no memory manager.</param>
+        <summary>Creates a new memory handle for the block of memory.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -79,7 +92,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Frees the pinned handle and releases the <see cref="T:System.Buffers.IPinnable" /> instance.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -106,9 +119,9 @@
         <ReturnType>System.Void*</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Returns a pointer to the memory block.</summary>
+        <value>A pointer to the memory block.</value>
+        <remarks>The memory is assumed to be pinned so that its address won't change.</remarks>
       </Docs>
     </Member>
   </Members>