Documentation for Memory<T>, IMemoryOwner<T> (#548)

* Initial checkin

* second check-in

* Documented Memory<T>

* Additional commit

* Incremental commit

* Added some detail

* Fixed malformed XML

* Fixed more malformed XML

* more malformed xml

* Incorporated reveiw comments

* Minor changes

* Addressed feedback, fixed invalid XML

* Added code, fixed bad xrefs

* Fixed broken links

* Corrected final bad xref

Author: Ron Petrusha

xml/System.Buffers/IMemoryOwner`1.xml

@@ -22,14 +22,24 @@
   </Interfaces>
   <Docs>
     <typeparam name="T">The type of elements to store in memory.</typeparam>
-    <summary>Defines the owner responsible for the lifetime management of a <see cref="System.Memory`1" /> buffer.</summary>
+    <summary>Identifies the owner of a block of memory who is responsible for disposing of the underlying memory appropriately. </summary>
     <remarks>
-<format type="text/markdown"><![CDATA[  
+      <format type="text/markdown"><![CDATA[  
 
-The `IMemoryOwner<T>` interface defines the owner responsible for the lifetime management of a <xref:System.Memory%601> buffer, who is responsible for disposing of the underlying memory appropriately.
-An instance of the `IMemoryOwner<T>` interface is returned by the <xref:System.Buffers.MemoryPool%601.Rent%2A?displayProperty=nameWithType> method.
+The `IMemoryOwner<T>` interface is used to define the owner responsible for the lifetime management of a <xref:System.Memory%601> buffer. An instance of the `IMemoryOwner<T>` interface is returned by the <xef:System.Buffers.MemoryPool%601.Rent%2A?displayProperty=nameWithType> method. 
+
+While a buffer can have multiple consumers, it can only have a single owner at any given time. The owner can:
+
+- Create the buffer either directly or by calling a factory method.
+
+- Transfer ownership to another consumer. In this case, the previous owner should no longer use the buffer.
+
+- Destroy the buffer when it is no longer in use.
+
+Because the `IMemoryOwner<T>` object implements the <xref:System.IDisposable> interface, you should call its <xref:System.IDisposable.Dispose%2A> method only after the memory buffer is no longer needed and you have destroyed it. You should *not* dispose of the `IMemoryOnwer<T>` object while a reference to its memory is available. This means that the type in which `IMemoryOwner<T>` is declared should not have a <xref:System.Object.Finalize%2A> method.
+
+   ]]></format>
 
-]]></format>
     </remarks>
   </Docs>
   <Members>
@@ -52,8 +62,8 @@ An instance of the `IMemoryOwner<T>` interface is returned by the <xref:System.B
         <ReturnType>System.Memory&lt;T&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets the associated <see cref="System.Memory`1" /> buffer.</summary>
-        <value>The associated <see cref="System.Memory`1" /> buffer.</value>
+        <summary>Gets the memory belonging to this owner.</summary>
+        <value>The memory belonging to this owner.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>