Port System.Collections.Immutable source comments to Docs (#2492)

* Port System.Collections.Immutable source comments to Docs

* Update xml/System.Collections.Immutable/ImmutableArray`1+Enumerator.xml

suggestion by rpetrusha

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

Author: carlossanlop

xml/System.Collections.Immutable/ImmutableArray.xml

@@ -406,7 +406,13 @@
 
  Creates an immutable array with the specified objects from another immutable array.</summary>
         <returns>An immutable array that contains the specified objects from the source array.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+          
+This overload allows helper methods or custom builder classes to efficiently avoid paying a redundant tax for copying an array when the new array is a segment of an existing array.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Create&lt;T&gt;">
@@ -486,7 +492,13 @@
 
  Creates an immutable array with specified objects from another array.</summary>
         <returns>An immutable array that contains the specified objects from the source array.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+          
+This overload allows helper methods or custom builder classes to efficiently avoid paying a redundant tax for copying an array when the new array is a segment of an existing array.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Create&lt;T&gt;">

xml/System.Collections.Immutable/ImmutableArray`1+Enumerator.xml

@@ -25,7 +25,14 @@
     <summary>An array enumerator.  
 
  **NuGet package**: <see href="https://www.nuget.org/packages/System.Collections.Immutable/">System.Collections.Immutable</see> (<see href="https://docs.microsoft.com/dotnet/api/system.collections.immutable?#remarks">about immutable collections and how to install</see>)</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+      
+> [!IMPORTANT]
+> This enumerator should **not** implement <xref:System.IDisposable>. The iterator should inline in a `foreach` loop and not result in a `try/finally` frame in the client.
+
+      ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="Current">
@@ -83,4 +90,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>