fix up priorityqueue comments (#7350)

Author: gewarren

xml/System.Collections.Generic/PriorityQueue`2.xml

@@ -20,14 +20,13 @@
   <Docs>
     <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>
+    <summary>Represents a collection of items that have a value and a priority. On dequeue, the item with the lowest priority value is removed.</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.
+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 are dequeued first.
 
       ]]></format>
     </remarks>
@@ -102,8 +101,7 @@ Implements an array-backed quaternary min-heap. Each element is enqueued with an
 
 ## Remarks
 
-Constructs the heap using a heapify operation,
-             which is generally faster than enqueuing individual elements sequentially.
+Constructs the heap using a heapify operation, which is generally faster than enqueuing individual elements sequentially.
 
           ]]></format>
         </remarks>
@@ -165,8 +163,7 @@ Constructs the heap using a heapify operation,
 
 ## Remarks
 
-Constructs the heap using a heapify operation,
-             which is generally faster than enqueuing individual elements sequentially.
+Constructs the heap using a heapify operation, which is generally faster than enqueuing individual elements sequentially.
 
           ]]></format>
         </remarks>
@@ -236,7 +233,7 @@ Constructs the heap using a heapify operation,
       </ReturnValue>
       <Docs>
         <summary>Gets the priority comparer used by the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</summary>
-        <value>To be added.</value>
+        <value>The comparer that determines the priority of items in the queue.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -257,7 +254,7 @@ Constructs the heap using a heapify operation,
       </ReturnValue>
       <Docs>
         <summary>Gets the number of elements contained in the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</summary>
-        <value>To be added.</value>
+        <value>The number of elements contained in the queue.</value>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -278,7 +275,7 @@ Constructs the heap using a heapify operation,
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>Removes and returns the minimal element from the <see cref="T:System.Collections.Generic.PriorityQueue`2" />.</summary>
+        <summary>Removes and returns the minimal element from the <see cref="T:System.Collections.Generic.PriorityQueue`2" /> - that is, the element with the lowest priority value.</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>
@@ -339,9 +336,7 @@ Constructs the heap using a heapify operation,
 
 ## 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.
+Implements an insert-then-extract heap operation that's generally more efficient than sequencing enqueue and dequeue operations.
 
           ]]></format>
         </remarks>
@@ -374,7 +369,7 @@ Implements an insert-then-extract heap operation that is generally more efficien
       </Parameters>
       <Docs>
         <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>
+        <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>
@@ -478,8 +473,7 @@ Implements an insert-then-extract heap operation that is generally more efficien
 
 ## Remarks
 
-This method can be used to minimize a collection's memory overhead
-             if no new elements will be added to the collection.
+This method can be used to minimize a collection's memory overhead if no new elements will be added to the collection.
 
           ]]></format>
         </remarks>
@@ -519,9 +513,9 @@ This method can be used to minimize a collection's memory overhead
         </Parameter>
       </Parameters>
       <Docs>
-        <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>
+        <param name="element">When this method returns, contains the removed element.</param>
+        <param name="priority">When this method returns, contains 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 and its associated priority to the <paramref name="element" /> and <paramref name="priority" /> arguments.</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>
@@ -561,10 +555,9 @@ This method can be used to minimize a collection's memory overhead
         </Parameter>
       </Parameters>
       <Docs>
-        <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>
+        <param name="element">When this method returns, contains the minimal element in the queue.</param>
+        <param name="priority">When this method returns, contains 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 and its associated priority to the <paramref name="element" /> and <paramref name="priority" /> arguments. 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>
@@ -593,8 +586,7 @@ This method can be used to minimize a collection's memory overhead
 
 ## 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.
+The enumeration does not order items by priority, since that would require N * log(N) time and N space. Instead, items are enumerated following the internal array heap layout.
 
           ]]></format>
         </remarks>