From 07540cfb5f7f872e4189802eddd813a964e81eb9 Mon Sep 17 00:00:00 2001
From: Dan Moseley <danmose@microsoft.com>
Date: Mon, 2 Aug 2021 22:39:33 -0600
Subject: [PATCH] Doc updates for collections

---
 .../ConcurrentDictionary`2.xml                |  17 +-
 xml/System.Collections.Generic/List`1.xml     |   5 +-
 ...`2+UnorderedItemsCollection+Enumerator.xml |  41 ++--
 ...iorityQueue`2+UnorderedItemsCollection.xml |  63 +++++--
 .../PriorityQueue`2.xml                       | 178 ++++++++++++------
 xml/System.Collections.Generic/Queue`1.xml    |   4 +-
 .../SortedList`2.xml                          |   2 +-
 xml/System.Collections.Generic/Stack`1.xml    |   5 +-
 8 files changed, 220 insertions(+), 95 deletions(-)

diff --git a/xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml b/xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml
index 86ef27985c5..2ff9cd11cdc 100644
--- a/xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml
+++ b/xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml
@@ -719,9 +719,20 @@
         <ReturnType>System.Collections.Generic.IEqualityComparer&lt;TKey&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets the <see cref="T:System.Collections.Generic.IEqualityComparer`1" /> that is used to determine equality of keys for the dictionary.</summary>
+        <value>The <see cref="T:System.Collections.Generic.IEqualityComparer`1" /> generic interface implementation that is used to determine equality of keys for the current <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> and to provide hash values for the keys.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+<xref:System.Collections.Concurrent.ConcurrentDictionary`2> requires an equality implementation to determine
+            whether keys are equal. You can specify an implementation of the <xref:System.Collections.Generic.IEqualityComparer`1>
+            generic interface by using a constructor that accepts a comparer parameter;
+            if you do not specify one, the default generic equality comparer <xref:System.Collections.Generic.EqualityComparer`1.Default> is used.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="ContainsKey">
diff --git a/xml/System.Collections.Generic/List`1.xml b/xml/System.Collections.Generic/List`1.xml
index fde59e3846b..a7935ca80cc 100644
--- a/xml/System.Collections.Generic/List`1.xml
+++ b/xml/System.Collections.Generic/List`1.xml
@@ -1418,8 +1418,9 @@
         <Parameter Name="capacity" Type="System.Int32" Index="0" FrameworkAlternate="net-6.0" />
       </Parameters>
       <Docs>
-        <param name="capacity">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="capacity">The minimum capacity to ensure.</param>
+        <summary>Ensures that the capacity of this list is at least the specified <paramref name="capacity" />.
+            If the current capacity of the list is less than specified <paramref name="capacity" />, the capacity is increased by continuously twice current capacity until it is at least the specified <paramref name="capacity" />.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
       </Docs>
diff --git a/xml/System.Collections.Generic/PriorityQueue`2+UnorderedItemsCollection+Enumerator.xml b/xml/System.Collections.Generic/PriorityQueue`2+UnorderedItemsCollection+Enumerator.xml
index 60dd900c3f4..4e36adc687c 100644
--- a/xml/System.Collections.Generic/PriorityQueue`2+UnorderedItemsCollection+Enumerator.xml
+++ b/xml/System.Collections.Generic/PriorityQueue`2+UnorderedItemsCollection+Enumerator.xml
@@ -28,7 +28,7 @@
     </Interface>
   </Interfaces>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Enumerates the element and priority pairs of a <see cref="T:System.Collections.Generic.PriorityQueue`2" />, without any ordering guarantees.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -57,7 +57,7 @@
         <ReturnType>System.ValueTuple&lt;TElement,TPriority&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the element at the current position of the enumerator.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -82,7 +82,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Releases all resources used by the <see cref="T:System.Collections.Generic.PriorityQueue`2.UnorderedItemsCollection.Enumerator" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -106,8 +106,9 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Advances the enumerator to the next element of the <see cref="P:System.Collections.Generic.PriorityQueue`2.UnorderedItems" />.</summary>
+        <returns>
+          <see langword="true" /> if the enumerator was successfully advanced to the next element; <see langword="false" /> if the enumerator has passed the end of the collection.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -136,8 +137,8 @@
         <ReturnType>System.ValueTuple&lt;TElement,TPriority&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the element in the collection at the current position of the enumerator.</summary>
+        <value>The element in the collection at the current position of the enumerator.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -160,9 +161,17 @@
         <ReturnType>System.Object</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets the element in the collection at the current position of the enumerator.</summary>
+        <value>The element in the collection at the current position of the enumerator.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This member is an explicit interface member implementation. It can be used only when the <xref:System.Collections.Generic.PriorityQueue`2.UnorderedItemsCollection.Enumerator> instance is cast to an <xref:System.Collections.IEnumerator> interface.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IEnumerator.Reset">
@@ -185,8 +194,16 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <summary>Sets the enumerator to its initial position, which is before the first element in the collection.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This member is an explicit interface member implementation. It can be used only when the <xref:System.Collections.Generic.PriorityQueue`2.UnorderedItemsCollection.Enumerator> instance is cast to an <xref:System.Collections.IEnumerator> interface.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>
diff --git a/xml/System.Collections.Generic/PriorityQueue`2+UnorderedItemsCollection.xml b/xml/System.Collections.Generic/PriorityQueue`2+UnorderedItemsCollection.xml
index 1bc509bf70f..8f82a20a576 100644
--- a/xml/System.Collections.Generic/PriorityQueue`2+UnorderedItemsCollection.xml
+++ b/xml/System.Collections.Generic/PriorityQueue`2+UnorderedItemsCollection.xml
@@ -34,7 +34,7 @@
     </Interface>
   </Interfaces>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Enumerates the contents of a <see cref="T:System.Collections.Generic.PriorityQueue`2" />, without any ordering guarantees.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -58,8 +58,8 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the number of elements in the collection.</summary>
+        <value>The number of elements in the collection.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -80,8 +80,8 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Returns an enumerator that iterates through the <see cref="P:System.Collections.Generic.PriorityQueue`2.UnorderedItems" />.</summary>
+        <returns>An <see cref="T:System.Collections.Generic.PriorityQueue`2.UnorderedItemsCollection.Enumerator" /> for the <see cref="P:System.Collections.Generic.PriorityQueue`2.UnorderedItems" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -111,8 +111,8 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Returns an enumerator that iterates through the collection.</summary>
+        <returns>An enumerator that can be used to iterate through the collection.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -139,9 +139,9 @@
         <Parameter Name="index" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <param name="array">To be added.</param>
-        <param name="index">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="array">The one-dimensional <see cref="T:System.Array" /> that is the destination of the elements copied from <see cref="T:System.Collections.ICollection" />. The <see cref="T:System.Array" /> must have zero-based indexing.</param>
+        <param name="index">The zero-based index in <paramref name="array" /> at which copying begins.</param>
+        <summary>Copies the elements of the <see cref="T:System.Collections.ICollection" /> to an <see cref="T:System.Array" />, starting at a particular <see cref="T:System.Array" /> index.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -164,9 +164,18 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets a value indicating whether access to the <see cref="T:System.Collections.ICollection" /> is synchronized (thread safe).</summary>
+        <value>
+          <see langword="true" /> if access to the <see cref="T:System.Collections.ICollection" /> is synchronized (thread safe); otherwise, <see langword="false" />.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This member is an explicit interface member implementation. It can be used only when the <xref:System.Collections.Generic.PriorityQueue`2.UnorderedItemsCollection> instance is cast to an <xref:System.Collections.ICollection> interface.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="System.Collections.ICollection.SyncRoot">
@@ -188,9 +197,17 @@
         <ReturnType>System.Object</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets an object that can be used to synchronize access to the <see cref="T:System.Collections.ICollection" />.</summary>
+        <value>An object that can be used to synchronize access to the <see cref="T:System.Collections.ICollection" />.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This member is an explicit interface member implementation. It can be used only when the <xref:System.Collections.Generic.PriorityQueue`2.UnorderedItemsCollection> instance is cast to an <xref:System.Collections.ICollection> interface.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="System.Collections.IEnumerable.GetEnumerator">
@@ -213,9 +230,17 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <summary>Returns an enumerator that iterates through a collection.</summary>
+        <returns>An <see cref="T:System.Collections.IEnumerator" /> object that can be used to iterate through the collection.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This member is an explicit interface member implementation. It can be used only when the <xref:System.Collections.Generic.PriorityQueue`2.UnorderedItemsCollection> instance is cast to an <xref:System.Collections.IEnumerable> interface.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>
diff --git a/xml/System.Collections.Generic/PriorityQueue`2.xml b/xml/System.Collections.Generic/PriorityQueue`2.xml
index b714d35653e..fc39f31e9a7 100644
--- a/xml/System.Collections.Generic/PriorityQueue`2.xml
+++ b/xml/System.Collections.Generic/PriorityQueue`2.xml
@@ -18,10 +18,19 @@
   </Base>
   <Interfaces />
   <Docs>
-    <typeparam name="TElement">To be added.</typeparam>
-    <typeparam name="TPriority">To be added.</typeparam>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <typeparam name="TElement">Specifies the type of elements in the queue.</typeparam>
+    <typeparam name="TPriority">Specifies the type of priority associated with enqueued elements.</typeparam>
+    <summary>Represents a min priority queue.</summary>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Implements an array-backed quaternary min-heap. Each element is enqueued with an associated priority
+             that determines the dequeue order: elements with the lowest priority get dequeued first.
+
+      ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -37,7 +46,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes a new instance of the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> class.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -57,8 +66,9 @@
         <Parameter Name="comparer" Type="System.Collections.Generic.IComparer&lt;TPriority&gt;" />
       </Parameters>
       <Docs>
-        <param name="comparer">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="comparer">Custom comparer dictating the ordering of elements.
+             Uses <see cref="P:System.Collections.Generic.Comparer`1.Default" /> if the argument is <see langword="null" />.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> class with the specified custom priority comparer.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -85,9 +95,19 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <param name="items">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="items">The pairs of elements and priorities with which to populate the queue.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> class that is populated with the specified elements and priorities.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Constructs the heap using a heapify operation,
+             which is generally faster than enqueuing individual elements sequentially.
+
+          ]]></format>
+        </remarks>
+        <exception cref="T:System.ArgumentNullException">The specified <paramref name="items" /> argument was <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -106,9 +126,10 @@
         <Parameter Name="initialCapacity" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <param name="initialCapacity">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="initialCapacity">Initial capacity to allocate in the underlying heap array.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> class with the specified initial capacity.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentOutOfRangeException">The specified <paramref name="initialCapacity" /> was negative.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -135,10 +156,21 @@
         <Parameter Name="comparer" Type="System.Collections.Generic.IComparer&lt;TPriority&gt;" />
       </Parameters>
       <Docs>
-        <param name="items">To be added.</param>
-        <param name="comparer">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="items">The pairs of elements and priorities with which to populate the queue.</param>
+        <param name="comparer">Custom comparer dictating the ordering of elements.
+             Uses <see cref="P:System.Collections.Generic.Comparer`1.Default" /> if the argument is <see langword="null" />.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> class that is populated with the specified elements and priorities, and with the specified custom priority comparer.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Constructs the heap using a heapify operation,
+             which is generally faster than enqueuing individual elements sequentially.
+
+          ]]></format>
+        </remarks>
+        <exception cref="T:System.ArgumentNullException">The specified <paramref name="items" /> argument was <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -158,10 +190,12 @@
         <Parameter Name="comparer" Type="System.Collections.Generic.IComparer&lt;TPriority&gt;" />
       </Parameters>
       <Docs>
-        <param name="initialCapacity">To be added.</param>
-        <param name="comparer">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="initialCapacity">Initial capacity to allocate in the underlying heap array.</param>
+        <param name="comparer">Custom comparer dictating the ordering of elements.
+             Uses <see cref="P:System.Collections.Generic.Comparer`1.Default" /> if the argument is <see langword="null" />.</param>
+        <summary>Initializes a new instance of the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> class with the specified initial capacity and custom priority comparer.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentOutOfRangeException">The specified <paramref name="initialCapacity" /> was negative.</exception>
       </Docs>
     </Member>
     <Member MemberName="Clear">
@@ -181,7 +215,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Removes all items from the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -201,7 +235,7 @@
         <ReturnType>System.Collections.Generic.IComparer&lt;TPriority&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the priority comparer used by the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -222,7 +256,7 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets the number of elements contained in the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -244,9 +278,10 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Removes and returns the minimal element from the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</summary>
+        <returns>The minimal element of the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.InvalidOperationException">The queue is empty.</exception>
       </Docs>
     </Member>
     <Member MemberName="Enqueue">
@@ -269,9 +304,9 @@
         <Parameter Name="priority" Type="TPriority" />
       </Parameters>
       <Docs>
-        <param name="element">To be added.</param>
-        <param name="priority">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="element">The element to add to the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</param>
+        <param name="priority">The priority with which to associate the new element.</param>
+        <summary>Adds the specified element with associated priority to the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -295,11 +330,21 @@
         <Parameter Name="priority" Type="TPriority" />
       </Parameters>
       <Docs>
-        <param name="element">To be added.</param>
-        <param name="priority">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="element">The element to add to the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</param>
+        <param name="priority">The priority with which to associate the new element.</param>
+        <summary>Adds the specified element with associated priority to the <see cref="T:System.Collections.Generic.PriorityQueue`2" />, and immediately removes the minimal element, returning the result.</summary>
+        <returns>The minimal element removed after the enqueue operation.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Implements an insert-then-extract heap operation that is generally more efficient
+             than sequencing Enqueue and Dequeue operations: in the worst case scenario only one
+             sift-down operation is required.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="EnqueueRange">
@@ -328,9 +373,10 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <param name="items">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="items">The pairs of elements and priorities to add to the queue.</param>
+        <summary>Enqueues a sequence of element/priority pairs to the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">The specified <paramref name="items" /> argument was <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="EnqueueRange">
@@ -353,10 +399,11 @@
         <Parameter Name="priority" Type="TPriority" />
       </Parameters>
       <Docs>
-        <param name="elements">To be added.</param>
-        <param name="priority">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="elements">The elements to add to the queue.</param>
+        <param name="priority">The priority to associate with the new elements.</param>
+        <summary>Enqueues a sequence of elements pairs to the <see cref="T:System.Collections.Generic.PriorityQueue`2" />, all associated with the specified priority.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException">The specified <paramref name="elements" /> argument was <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="EnsureCapacity">
@@ -378,10 +425,11 @@
         <Parameter Name="capacity" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <param name="capacity">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="capacity">The minimum capacity to be used.</param>
+        <summary>Ensures that the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> can hold up to <paramref name="capacity" /> items without further expansion of its backing storage.</summary>
+        <returns>The current capacity of the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentOutOfRangeException">The specified <paramref name="capacity" /> is negative.</exception>
       </Docs>
     </Member>
     <Member MemberName="Peek">
@@ -401,9 +449,10 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>Returns the minimal element from the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> without removing it.</summary>
+        <returns>The minimal element of the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.InvalidOperationException">The <see cref="T:System.Collections.Generic.PriorityQueue`2" /> is empty.</exception>
       </Docs>
     </Member>
     <Member MemberName="TrimExcess">
@@ -423,8 +472,17 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <summary>Sets the capacity to the actual number of items in the <see cref="T:System.Collections.Generic.PriorityQueue`2" />, if that is less than 90 percent of current capacity.</summary>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This method can be used to minimize a collection's memory overhead
+             if no new elements will be added to the collection.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="TryDequeue">
@@ -461,10 +519,11 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <param name="element">To be added.</param>
-        <param name="priority">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="element">The removed element.</param>
+        <param name="priority">The priority associated with the removed element.</param>
+        <summary>Removes the minimal element from the <see cref="T:System.Collections.Generic.PriorityQueue`2" />, and copies it to the <paramref name="element" /> parameter, and its associated priority to the <paramref name="priority" /> parameter.</summary>
+        <returns>
+          <see langword="true" /> if the element is successfully removed; <see langword="false" /> if the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> is empty.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -502,10 +561,12 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <param name="element">To be added.</param>
-        <param name="priority">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="element">The minimal element in the queue.</param>
+        <param name="priority">The priority associated with the minimal element.</param>
+        <summary>Returns a value that indicates whether there is a minimal element in the <see cref="T:System.Collections.Generic.PriorityQueue`2" />, and if one is present, copies it to the <paramref name="element" /> parameter, and its associated priority to the <paramref name="priority" /> parameter.
+             The element is not removed from the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</summary>
+        <returns>
+          <see langword="true" /> if there is a minimal element; <see langword="false" /> if the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> is empty.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -525,9 +586,18 @@
         <ReturnType>System.Collections.Generic.PriorityQueue&lt;TElement,TPriority&gt;+UnorderedItemsCollection</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets a collection that enumerates the elements of the queue in an unordered manner.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+The enumeration does not order items by priority, since that would require N * log(N) time and N space.
+             Items are instead enumerated following the internal array heap layout.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>
diff --git a/xml/System.Collections.Generic/Queue`1.xml b/xml/System.Collections.Generic/Queue`1.xml
index 57bab1ae27a..9b7c3455f43 100644
--- a/xml/System.Collections.Generic/Queue`1.xml
+++ b/xml/System.Collections.Generic/Queue`1.xml
@@ -733,8 +733,8 @@
         <Parameter Name="capacity" Type="System.Int32" Index="0" FrameworkAlternate="net-6.0" />
       </Parameters>
       <Docs>
-        <param name="capacity">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="capacity">The minimum capacity to ensure.</param>
+        <summary>Ensures that the capacity of this Queue is at least the specified <paramref name="capacity" />.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
       </Docs>
diff --git a/xml/System.Collections.Generic/SortedList`2.xml b/xml/System.Collections.Generic/SortedList`2.xml
index 84a3e7617cf..2b2d3015f41 100644
--- a/xml/System.Collections.Generic/SortedList`2.xml
+++ b/xml/System.Collections.Generic/SortedList`2.xml
@@ -1942,7 +1942,7 @@
       <Docs>
         <param name="array">The one-dimensional <see cref="T:System.Array" /> that is the destination of the elements copied from <see cref="T:System.Collections.ICollection" />. The <see cref="T:System.Array" /> must have zero-based indexing.</param>
         <param name="arrayIndex">The zero-based index in <paramref name="array" /> at which copying begins.</param>
-        <param name="index">To be added.</param>
+        <param name="index">The zero-based index in <paramref name="array" /> at which copying begins.</param>
         <summary>Copies the elements of the <see cref="T:System.Collections.ICollection" /> to an <see cref="T:System.Array" />, starting at a particular <see cref="T:System.Array" /> index.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
diff --git a/xml/System.Collections.Generic/Stack`1.xml b/xml/System.Collections.Generic/Stack`1.xml
index 9c771a2ce16..35c96ca1b12 100644
--- a/xml/System.Collections.Generic/Stack`1.xml
+++ b/xml/System.Collections.Generic/Stack`1.xml
@@ -638,8 +638,9 @@
         <Parameter Name="capacity" Type="System.Int32" Index="0" FrameworkAlternate="net-6.0" />
       </Parameters>
       <Docs>
-        <param name="capacity">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="capacity">The minimum capacity to ensure.</param>
+        <summary>Ensures that the capacity of this Stack is at least the specified <paramref name="capacity" />.
+            If the current capacity of the Stack is less than specified <paramref name="capacity" />, the capacity is increased by continuously twice current capacity until it is at least the specified <paramref name="capacity" />.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
       </Docs>