SI-9424 Clarify behavior of PriorityQueue toString

Clarified that PriorityQueue will not print in order and gave an example of a workaround if one needs it.

Documentation change only; no tests.

1 files changed, 13 insertions, 2 deletions

diff --git a/src/library/scala/collection/mutable/PriorityQueue.scala b/src/library/scala/collection/mutable/PriorityQueue.scala
index d3c4161e3b..2562f60355 100644
--- a/src/library/scala/collection/mutable/PriorityQueue.scala
+++ b/src/library/scala/collection/mutable/PriorityQueue.scala
@@ -18,8 +18,19 @@ import generic._
  *
  *  Only the `dequeue` and `dequeueAll` methods will return methods in priority
  *  order (while removing elements from the heap).  Standard collection methods
- *  including `drop` and `iterator` will remove or traverse the heap in whichever
- *  order seems most convenient.
+ *  including `drop`, `iterator`, and `toString` will remove or traverse the heap
+ *  in whichever order seems most convenient.
+ *
+ *  Therefore, printing a `PriorityQueue` will not reveal the priority order of
+ *  the elements, though the highest-priority element will be printed first.  To
+ *  print the elements in order, one must duplicate the `PriorityQueue` (by using
+ *  `clone`, for instance) and then dequeue them:
+ *
+ *  @example {{{
+ *  val pq = collection.mutable.PriorityQueue(1, 2, 5, 3, 7)
+ *  println(pq)                  // elements probably not in order
+ *  println(pq.clone.dequeueAll) // prints Vector(7, 5, 3, 2, 1)
+ *  }}}
  *
  *  @tparam A    type of the elements in this priority queue.
  *  @param ord   implicit ordering used to compare the elements of type `A`.