Add missing docs for System.Collections.Immutable

xml/System.Collections.Immutable/ImmutableArray.xml

@@ -679,12 +679,12 @@ This overload allows helper methods or custom builder classes to efficiently avo
         <Parameter Name="selector" Type="System.Func&lt;TSource,TResult&gt;" />
       </Parameters>
       <Docs>
-        <typeparam name="TSource">To be added.</typeparam>
-        <typeparam name="TResult">To be added.</typeparam>
+        <typeparam name="TSource">The type of element stored in the source array.</typeparam>
+        <typeparam name="TResult">The type of element to be stored in the target array.</typeparam>
         <param name="items">The source array to initialize the resulting array with.</param>
         <param name="selector">The function to apply to each element from the source array.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> struct.</summary>
-        <returns>To be added.</returns>
+        <returns>An immutable array that contains the specified items.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
 
@@ -728,14 +728,14 @@ This overload allows helper methods or custom builder classes to efficiently avo
         <Parameter Name="selector" Type="System.Func&lt;TSource,TResult&gt;" />
       </Parameters>
       <Docs>
-        <typeparam name="TSource">To be added.</typeparam>
-        <typeparam name="TResult">To be added.</typeparam>
+        <typeparam name="TSource">The type of element stored in the source array.</typeparam>
+        <typeparam name="TResult">The type of element to be stored in the target array.</typeparam>
         <param name="items">The source array to initialize the resulting array with.</param>
         <param name="start">The index of the first element in the source array to include in the resulting array.</param>
         <param name="length">The number of elements from the source array to include in the resulting array.</param>
         <param name="selector">The function to apply to each element from the source array included in the resulting array.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> struct.</summary>
-        <returns>To be added.</returns>
+        <returns>An immutable array that contains the specified items.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
 
@@ -779,14 +779,14 @@ This overload allows helper methods or custom builder classes to efficiently avo
         <Parameter Name="arg" Type="TArg" />
       </Parameters>
       <Docs>
-        <typeparam name="TSource">To be added.</typeparam>
-        <typeparam name="TArg">To be added.</typeparam>
-        <typeparam name="TResult">To be added.</typeparam>
+        <typeparam name="TSource">The type of element stored in the source array.</typeparam>
+        <typeparam name="TArg">The type of argument to be passed to the selector mapping function.</typeparam>
+        <typeparam name="TResult">The type of element to be stored in the target array.</typeparam>
         <param name="items">The source array to initialize the resulting array with.</param>
         <param name="selector">The function to apply to each element from the source array.</param>
         <param name="arg">An argument to be passed to the selector mapping function.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> struct.</summary>
-        <returns>To be added.</returns>
+        <returns>An immutable array that contains the specified items.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
 
@@ -832,16 +832,16 @@ This overload allows helper methods or custom builder classes to efficiently avo
         <Parameter Name="arg" Type="TArg" />
       </Parameters>
       <Docs>
-        <typeparam name="TSource">To be added.</typeparam>
-        <typeparam name="TArg">To be added.</typeparam>
-        <typeparam name="TResult">To be added.</typeparam>
+        <typeparam name="TSource">The type of element stored in the source array.</typeparam>
+        <typeparam name="TArg">The type of argument to be passed to the selector mapping function.</typeparam>
+        <typeparam name="TResult">The type of element to be stored in the target array.</typeparam>
         <param name="items">The source array to initialize the resulting array with.</param>
         <param name="start">The index of the first element in the source array to include in the resulting array.</param>
         <param name="length">The number of elements from the source array to include in the resulting array.</param>
         <param name="selector">The function to apply to each element from the source array included in the resulting array.</param>
         <param name="arg">An argument to be passed to the selector mapping function.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> struct.</summary>
-        <returns>To be added.</returns>
+        <returns>An immutable array that contains the specified items.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
 

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

@@ -1,4 +1,4 @@
-<Type Name="ImmutableArray&lt;T&gt;+Builder" FullName="System.Collections.Immutable.ImmutableArray&lt;T&gt;+Builder">
+<Type Name="ImmutableArray&lt;T&gt;+Builder" FullName="System.Collections.Immutable.ImmutableArray&lt;T&gt;+Builder">
   <TypeSignature Language="C#" Value="public sealed class ImmutableArray&lt;T&gt;.Builder : System.Collections.Generic.ICollection&lt;T&gt;, System.Collections.Generic.IEnumerable&lt;T&gt;, System.Collections.Generic.IList&lt;T&gt;, System.Collections.Generic.IReadOnlyCollection&lt;T&gt;, System.Collections.Generic.IReadOnlyList&lt;T&gt;" />
   <TypeSignature Language="ILAsm" Value=".class nested public auto ansi sealed beforefieldinit ImmutableArray`1/Builder&lt;T&gt; extends System.Object implements class System.Collections.Generic.ICollection`1&lt;!T&gt;, class System.Collections.Generic.IEnumerable`1&lt;!T&gt;, class System.Collections.Generic.IList`1&lt;!T&gt;, class System.Collections.Generic.IReadOnlyCollection`1&lt;!T&gt;, class System.Collections.Generic.IReadOnlyList`1&lt;!T&gt;, class System.Collections.IEnumerable" />
   <TypeSignature Language="DocId" Value="T:System.Collections.Immutable.ImmutableArray`1.Builder" />
@@ -461,7 +461,15 @@
       <Parameters />
       <Docs>
         <summary>Removes all items from the array.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+<xref:System.Collections.Generic.ICollection%601.Count%2A> must be set to 0, and references to other objects from elements of the collection must be released.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Contains">
@@ -497,7 +505,15 @@
         <summary>Determines whether the array contains a specific value.</summary>
         <returns>
           <see langword="true" /> if the object is found; otherwise, <see langword="false" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Implementations can vary in how they determine equality of objects; for example, <xref:System.Collections.Generic.List%601> uses <xref:System.Collections.Generic.Comparer%601.Default%2A?displayProperty=nameWithType>, whereas <xref:System.Collections.Generic.Dictionary%602> allows the user to specify the <xref:System.Collections.Generic.IComparer%601> implementation to use for comparing keys.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="CopyTo">
@@ -611,7 +627,25 @@
       <Docs>
         <summary>Gets an object that can be used to iterate through the collection.</summary>
         <returns>An object that can be used to iterate through the collection.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The returned <xref:System.Collections.Generic.IEnumerator%601> provides the ability to iterate through the collection by exposing a <xref:System.Collections.Generic.IEnumerator%601.Current%2A> property .You can use enumerators to read the data in a collection, but not to modify the collection.   
+ Initially, the enumerator is positioned before the first element in the collection. At this position, <xref:System.Collections.Generic.IEnumerator%601.Current%2A> is undefined. Therefore, you must call the <xref:System.Collections.IEnumerator.MoveNext%2A> method to advance the enumerator to the first element of the collection before reading the value of <xref:System.Collections.Generic.IEnumerator%601.Current%2A>.   
+ <xref:System.Collections.Generic.IEnumerator%601.Current%2A> returns the same object until <xref:System.Collections.IEnumerator.MoveNext%2A> is called again as <xref:System.Collections.IEnumerator.MoveNext%2A> sets <xref:System.Collections.Generic.IEnumerator%601.Current%2A> to the next element.   
+ If <xref:System.Collections.IEnumerator.MoveNext%2A> passes the end of the collection, the enumerator is positioned after the last element in the collection and <xref:System.Collections.IEnumerator.MoveNext%2A> returns `false`. When the enumerator is at this position, subsequent calls to <xref:System.Collections.IEnumerator.MoveNext%2A> also return `false`. If the last call to <xref:System.Collections.IEnumerator.MoveNext%2A> returned `false`, <xref:System.Collections.Generic.IEnumerator%601.Current%2A> is undefined. You cannot set <xref:System.Collections.Generic.IEnumerator%601.Current%2A> to the first element of the collection again; you must create a new enumerator instance instead.   If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined.   
+ An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection.   
+ Default implementations of collections in the <xref:System.Collections.Generic?displayProperty=nameWithType> namespace aren't synchronized.   
+ 
+ 
+ ## Examples   The following example demonstrates how to implement the <xref:System.Collections.Generic.IEnumerable%601> interface and uses that implementation to create a LINQ query. When you implement <xref:System.Collections.Generic.IEnumerable%601>, you must also implement <xref:System.Collections.Generic.IEnumerator%601> or, for C# only, you can use the [yield](~/docs/csharp/language-reference/keywords/yield.md) keyword. Implementing <xref:System.Collections.Generic.IEnumerator%601> also requires <xref:System.IDisposable> to be implemented, which you will see in this example.   
+ [!code-csharp[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/cs/program.cs#1)] [!code-vb[System.Collections.Generic.IEnumerableEx#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.ienumerableex/vb/module1.vb#1)]   
+ For another C# example that demonstrates how to implement the <xref:System.Collections.Generic.IEnumerable%601> interface, see the [Generics Sample](https://code.msdn.microsoft.com/Generics-Sample-C-9b41a192/sourcecode?fileId=46476&pathId=1364935593). This sample uses of the `yield` keyword instead of implementing <xref:System.Collections.Generic.IEnumerator%601>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="IndexOf">
@@ -646,7 +680,15 @@
         <param name="item">The item to locate in the array.</param>
         <summary>Determines the index of a specific item in the array.</summary>
         <returns>The index of <paramref name="item" /> if it's found in the list; otherwise, -1.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If an object occurs multiple times in the list, the <xref:System.Collections.Generic.IList%601.IndexOf%2A> method always returns the first instance found.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="IndexOf">
@@ -790,7 +832,16 @@
         <param name="index">The zero-based index at which to insert the item.</param>
         <param name="item">The object to insert into the array.</param>
         <summary>Inserts an item in the array at the specified index.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+If `index` equals the number of items in the <xref:System.Collections.Generic.IList%601>, then `item` is appended to the list.   
+ In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Item">
@@ -825,7 +876,16 @@
         <param name="index">The index of the item to get or set.</param>
         <summary>Gets or sets the item at the specified index.</summary>
         <value>The item at the specified index.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`.   
+ The C# language uses the [this](~/docs/csharp/language-reference/keywords/this.md) keyword to define the indexers instead of implementing the <xref:System.Collections.Generic.IList%601.Item%2A> property. Visual Basic implements <xref:System.Collections.Generic.IList%601.Item%2A> as a [default property](~/docs/visual-basic/language-reference/modifiers/default.md), which provides the same indexing functionality.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.IndexOutOfRangeException">The specified index is not in the array.</exception>
       </Docs>
     </Member>
@@ -1029,7 +1089,7 @@
       <Parameters />
       <Docs>
         <summary>Extracts the internal array as an <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> and replaces it              with a zero length array.</summary>
-        <returns>To be added.</returns>
+        <returns>An immutable array containing the elements of the builder.</returns>
         <remarks>To be added.</remarks>
         <exception cref="T:System.InvalidOperationException">When <see cref="P:System.Collections.Immutable.ImmutableArray`1.Builder.Count" /> doesn't              equal <see cref="P:System.Collections.Immutable.ImmutableArray`1.Builder.Capacity" />.</exception>
       </Docs>
@@ -1067,7 +1127,16 @@
         <summary>Removes the specified element.</summary>
         <returns>
           <see langword="true" /> if <paramref name="element" /> was found and removed; otherwise, <see langword="false" />.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Implementations can vary in how they determine equality of objects; for example, <xref:System.Collections.Generic.List%601> uses <xref:System.Collections.Generic.Comparer%601.Default%2A?displayProperty=nameWithType>, whereas, <xref:System.Collections.Generic.Dictionary%602> allows the user to specify the <xref:System.Collections.Generic.IComparer%601> implementation to use for comparing keys.   
+ In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="RemoveAt">
@@ -1101,7 +1170,15 @@
       <Docs>
         <param name="index">The zero-based index of the item to remove.</param>
         <summary>Removes the item at the specified index from the array.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Reverse">
@@ -1287,7 +1364,15 @@
         <summary>Gets a value that indicates whether the <see cref="T:System.Collections.Generic.ICollection`1" /> is read-only.</summary>
         <value>
           <see langword="true" /> if the <see cref="T:System.Collections.Generic.ICollection`1" /> is read-only; otherwise, <see langword="false" />.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the <xref:System.Collections.Generic.ICollection%601> interface only supports addition and removal operations. For example, the <xref:System.Collections.Generic.ICollection%601.IsReadOnly%2A> property of an array that is cast or converted to an <xref:System.Collections.Generic.ICollection%601> object returns `true`, even though individual array elements can be modified.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="System.Collections.Generic.IEnumerable&lt;T&gt;.GetEnumerator">