Ported System.Collections source code comments to Docs (#2306)

* Ported System.Collections source code comments to Docs

* Apply suggestions from code review

Applying suggestions provided by rpetrusha.

Co-Authored-By: carlossanlop <[email protected]>

* Fixed link.

* Fixed broken xrefs

Author: carlossanlop

xml/System.Collections.Concurrent/BlockingCollection`1.xml

@@ -1249,6 +1249,7 @@
         <exception cref="T:System.InvalidOperationException">The underlying collection was modified outside of this <see cref="T:System.Collections.Concurrent.BlockingCollection`1" /> instance, or the <see cref="T:System.Collections.Concurrent.BlockingCollection`1" /> is empty and the collection has been marked as complete for adding.</exception>
         <related type="Article" href="https://msdn.microsoft.com/library/2e7ca21f-786c-4367-96be-0cf3f3dcc6bd">Thread-Safe Collections</related>
         <related type="Article" href="https://msdn.microsoft.com/library/987ea3d7-0ad5-4238-8b64-331ce4eb3f0b">BlockingCollection Overview</related>
+        <exception cref="T:System.OperationCanceledException">The <see cref="T:System.Collections.Concurrent.BlockingCollection`1" /> is empty and has been marked as complete with regards to additions.</exception>
       </Docs>
     </Member>
     <Member MemberName="Take">
@@ -2415,4 +2416,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml

@@ -597,6 +597,7 @@
         </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="key" />, <paramref name="addValueFactory" />, or <paramref name="updateValueFactory" /> is a null reference (Nothing in Visual Basic).</exception>
+        <exception cref="T:System.OverflowException">The dictionary contains too many elements.</exception>
       </Docs>
     </Member>
     <Member MemberName="Clear">
@@ -972,6 +973,8 @@
   
  ]]></format>
         </remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="key" /> is a <see langword="null" /> reference (Nothing in Visual Basic).</exception>
+        <exception cref="T:System.OverflowException">The dictionary contains too many elements.</exception>
       </Docs>
     </Member>
     <Member MemberName="IsEmpty">

xml/System.Collections.Immutable/IImmutableQueue`1.xml

@@ -92,6 +92,7 @@
         <summary>Removes the first element in the immutable queue, and returns the new queue.</summary>
         <returns>The new immutable queue with the first element removed. This value is never <c>null</c>.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.InvalidOperationException">The queue is empty.</exception>
       </Docs>
     </Member>
     <Member MemberName="Enqueue">
@@ -176,7 +177,8 @@
         <summary>Returns the element at the beginning of the immutable queue without removing it.</summary>
         <returns>The element at the beginning of the queue.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.InvalidOperationException">The queue is empty.</exception>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Collections.Immutable/IImmutableStack`1.xml

@@ -112,6 +112,7 @@
         <summary>Returns the element at the top of the immutable stack without removing it.</summary>
         <returns>The element at the top of the stack.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.InvalidOperationException">The stack is empty.</exception>
       </Docs>
     </Member>
     <Member MemberName="Pop">
@@ -139,6 +140,7 @@
         <summary>Removes the element at the top of the immutable stack and returns the new stack.</summary>
         <returns>The new stack; never <c>null</c></returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.InvalidOperationException">The stack is empty.</exception>
       </Docs>
     </Member>
     <Member MemberName="Push">
@@ -172,4 +174,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Collections.Immutable/ImmutableArray.xml

@@ -152,6 +152,12 @@
         <remarks>To be added.</remarks>
         <exception cref="T:System.InvalidOperationException">
           <paramref name="value" /> does not implement <see cref="T:System.IComparable" /> or the search encounters an element that does not implement <see cref="T:System.IComparable" />.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="index" /> and <paramref name="length" /> do not specify a valid range in <paramref name="array" />.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="index" /> is less than the lower bound of <paramref name="array" />.
+        
+-or-
+
+<paramref name="length" /> is less than zero.</exception>
       </Docs>
     </Member>
     <Member MemberName="BinarySearch&lt;T&gt;">
@@ -198,6 +204,16 @@
         <remarks>To be added.</remarks>
         <exception cref="T:System.InvalidOperationException">
           <paramref name="comparer" /> is null and <paramref name="value" /> does not implement <see cref="T:System.IComparable" /> or the search encounters an element that does not implement <see cref="T:System.IComparable" />.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="index" /> and <paramref name="length" /> do not specify a valid range in <paramref name="array" />.
+        
+-or-
+
+<paramref name="comparer" /> is <see langword="null" />, and <paramref name="value" /> is of a type that is not compatible with the elements of <paramref name="array" />.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="index" /> is less than the lower bound of <paramref name="array" />.
+
+-or-
+
+<paramref name="length" /> is less than zero.</exception>
       </Docs>
     </Member>
     <Member MemberName="Create&lt;T&gt;">
@@ -877,4 +893,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

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

@@ -805,10 +805,11 @@
         <Parameter Name="index" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <param name="index">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="index">The item index.</param>
+        <summary>Gets a read-only reference to the element at the specified index.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.IndexOutOfRangeException"><paramref name="index" /> is greater or equal to the array count.</exception>
       </Docs>
     </Member>
     <Member MemberName="LastIndexOf">
@@ -1338,4 +1339,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

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

@@ -1042,9 +1042,9 @@
         <Parameter Name="index" Type="System.Int32" Index="0" FrameworkAlternate="netcore-2.1" />
       </Parameters>
       <Docs>
-        <param name="index">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="index">The zero-based index of the element to get a reference to.</param>
+        <summary>Gets a read-only reference to the element at the specified <paramref name="index" /> in the read-only list.</summary>
+        <returns>A read-only reference to the element at the specified <paramref name="index" /> in the read-only list.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -2443,6 +2443,7 @@
         <summary>Returns an enumerator that iterates through the immutable array.</summary>
         <returns>An enumerator that iterates through the immutable array.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.InvalidOperationException">The <see cref="P:System.Collections.Immutable.ImmutableArray`1.IsDefault" /> property returns <see langword="true" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.Add">
@@ -2475,6 +2476,7 @@
         <summary>Throws <see cref="T:System.NotSupportedException" /> in all cases.</summary>
         <returns>Throws <see cref="T:System.NotSupportedException" /> in all cases.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.NotSupportedException">Thrown in all cases.</exception>
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.Clear">
@@ -2503,6 +2505,7 @@
       <Docs>
         <summary>Throws <see cref="T:System.NotSupportedException" /> in all cases.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.NotSupportedException">Thrown in all cases.</exception>
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.Contains">
@@ -2600,6 +2603,7 @@
         <param name="value">The value to insert.</param>
         <summary>Throws <see cref="T:System.NotSupportedException" /> in all cases.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.NotSupportedException">Thrown in all cases.</exception>
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.IsFixedSize">
@@ -2736,6 +2740,7 @@
         <param name="value">The value to remove from the array.</param>
         <summary>Throws <see cref="T:System.NotSupportedException" /> in all cases.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.NotSupportedException">Thrown in all cases.</exception>
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IList.RemoveAt">
@@ -2767,6 +2772,7 @@
         <param name="index">The index of the item to remove.</param>
         <summary>Throws <see cref="T:System.NotSupportedException" /> in all cases.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.NotSupportedException">Thrown in all cases.</exception>
       </Docs>
     </Member>
     <Member MemberName="System.Collections.Immutable.IImmutableList&lt;T&gt;.Add">
@@ -3403,4 +3409,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml

@@ -456,6 +456,9 @@
         <summary>Gets or sets the element with the specified key.</summary>
         <value>The element that has the specified key.</value>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="key" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.Collections.Generic.KeyNotFoundException">The property is being retrieved, and <paramref name="key" /> is not found.</exception>
+        <exception cref="T:System.NotSupportedException">The property is being set, and the <see cref="T:System.Collections.Generic.IDictionary`2" /> is read-only.</exception>
       </Docs>
     </Member>
     <Member MemberName="KeyComparer">
@@ -1401,4 +1404,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Collections.Immutable/ImmutableInterlocked.xml

@@ -57,8 +57,8 @@
         <Parameter Name="updateValueFactory" Type="System.Func&lt;TKey,TValue,TValue&gt;" />
       </Parameters>
       <Docs>
-        <typeparam name="TKey">To be added.</typeparam>
-        <typeparam name="TValue">To be added.</typeparam>
+        <typeparam name="TKey">The type of key stored by the dictionary.</typeparam>
+        <typeparam name="TValue">The type of value stored by the dictionary.</typeparam>
         <param name="location">The variable or field to atomically update if the specified  is not in the dictionary.</param>
         <param name="key">The key for the value to add or update.</param>
         <param name="addValueFactory">The function that receives the key and returns a new value to add to the dictionary when no value previously exists.</param>
@@ -99,8 +99,8 @@
         <Parameter Name="updateValueFactory" Type="System.Func&lt;TKey,TValue,TValue&gt;" />
       </Parameters>
       <Docs>
-        <typeparam name="TKey">To be added.</typeparam>
-        <typeparam name="TValue">To be added.</typeparam>
+        <typeparam name="TKey">The type of key stored by the dictionary.</typeparam>
+        <typeparam name="TValue">The type of value stored by the dictionary.</typeparam>
         <param name="location">The variable or field to atomically update if the specified  is not in the dictionary.</param>
         <param name="key">The key for the value to add or update.</param>
         <param name="addValue">The value to use if no previous value exists.</param>
@@ -259,7 +259,7 @@
       <Docs>
         <typeparam name="TKey">The type of the keys contained in the collection.</typeparam>
         <typeparam name="TValue">The type of the values contained in the collection.</typeparam>
-        <typeparam name="TArg">To be added.</typeparam>
+        <typeparam name="TArg">The type of the argument supplied to the value factory.</typeparam>
         <param name="location">The variable or field to update if the specified is not in the dictionary.</param>
         <param name="key">The key for the value to retrieve or add.</param>
         <param name="valueFactory">The function to execute to obtain the value to insert into the dictionary if the key is not found.</param>
@@ -707,4 +707,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

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

@@ -164,6 +164,7 @@
   
  ]]></format>
         </remarks>
+        <exception cref="T:System.InvalidOperationException">The default comparer <see cref="P:System.Collections.Generic.Comparer`1.Default" /> cannot find an implementation of the <see cref="T:System.IComparable`1" /> generic interface or the <see cref="T:System.IComparable" /> interface for type T.</exception>
       </Docs>
     </Member>
     <Member MemberName="BinarySearch">
@@ -203,6 +204,8 @@
   
  ]]></format>
         </remarks>
+        <exception cref="T:System.InvalidOperationException"><paramref name="comparer" /> is <see langword="null" />, and the default comparer <see cref="P:System.Collections.Generic.Comparer`1.Default" /> cannot find an implementation of the <see cref="T:System.IComparable`1" /> generic interface or the <see cref="T:System.IComparable" /> interface for type T.
+            </exception>
       </Docs>
     </Member>
     <Member MemberName="BinarySearch">
@@ -246,6 +249,12 @@
   
  ]]></format>
         </remarks>
+        <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="index" /> is less than 0.
+-or-
+
+<paramref name="count" /> is less than 0.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="index" /> and <paramref name="count" /> do not denote a valid range in the <see cref="T:System.Collections.Generic.List`1" />.</exception>
+        <exception cref="T:System.InvalidOperationException"><paramref name="comparer" /> is <see langword="null" />, and the default comparer <see cref="P:System.Collections.Generic.Comparer`1.Default" /> cannot find an implementation of the <see cref="T:System.IComparable`1" /> generic interface or the <see cref="T:System.IComparable" /> interface for type T.</exception>
       </Docs>
     </Member>
     <Member MemberName="Clear">
@@ -1133,9 +1142,9 @@
         <Parameter Name="index" Type="System.Int32" Index="0" FrameworkAlternate="netcore-2.2" />
       </Parameters>
       <Docs>
-        <param name="index">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="index">The index of the desired element.</param>
+        <summary>Gets a read-only reference to the value for a given <paramref name="index" /> into the list.</summary>
+        <returns>A read-only reference to the value at the specified <paramref name="index" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -1507,6 +1516,7 @@
         <param name="comparison">The object to use when comparing elements.</param>
         <summary>Sorts the elements in the entire immutable list by using the specified comparison object.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="comparison" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="Sort">
@@ -2148,4 +2158,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>