Merge pull request scala/scala#7144 from martijnhoekstra/SI-11079

Update documentation of PriorityQueue

Author: SethTisue

library/src/scala/collection/mutable/PriorityQueue.scala

@@ -15,6 +15,12 @@ import generic._
 /** This class implements priority queues using a heap.
  *  To prioritize elements of type A there must be an implicit
  *  Ordering[A] available at creation.
+ * 
+ *  If multiple elements have the same priority in the ordering of this
+ *  PriorityQueue, no guarantees are made regarding the order in which elements
+ *  are returned by `dequeue` or `dequeueAll`. In particular, that means this
+ *  class does not guarantee first in first out behaviour that may be
+ *  incorrectly inferred from the Queue part of the name of this class.
  *
  *  Only the `dequeue` and `dequeueAll` methods will return elements in priority
  *  order (while removing elements from the heap).  Standard collection methods