Improve doc for sizeHint

Author: som-snytt

library/src/scala/collection/mutable/Builder.scala

@@ -30,31 +30,45 @@ trait Builder[-A, +To] extends Growable[A] { self =>
   /** Result collection consisting of all elements appended so far. */
   def result(): To
 
-  /** Gives a hint how many elements are expected to be added
-    *  when the next `result` is called. Some builder classes
-    *  will optimize their representation based on the hint. However,
-    *  builder implementations are still required to work correctly even if the hint is
-    *  wrong, i.e. a different number of elements is added.
-    *
-    *  @param size  the hint how many elements will be added.
-    */
+  /** Gives a hint how many elements are expected to be added in total
+   *  by the time `result` is called.
+   *
+   *  Some builder classes will optimize their representation based on the hint.
+   *  However, builder implementations are required to work correctly even if the hint is
+   *  wrong, i.e., if a different number of elements is added.
+   *
+   *  The semantics of supplying a hint out of range, such as a size that is negative
+   *  or unreasonably large, is not specified but is implementation-dependent.
+   *
+   *  The default implementation simply ignores the hint.
+   *
+   *  @param size  the hint how many elements will be added.
+   */
   def sizeHint(size: Int): Unit = ()
 
-  /** Gives a hint that one expects the `result` of this builder
-    *  to have the same size as the given collection, plus some delta. This will
-    *  provide a hint only if the collection has a known size
-    *  Some builder classes
-    *  will optimize their representation based on the hint. However,
-    *  builder implementations are still required to work correctly even if the hint is
-    *  wrong, i.e. a different number of elements is added.
-    *
-    *  @param coll  the collection which serves as a hint for the result's size.
-    *  @param delta a correction to add to the `coll.size` to produce the size hint.
-    */
-  final def sizeHint(coll: scala.collection.IterableOnce[_], delta: Int = 0): Unit = {
-    val s = coll.knownSize
-    if (s != -1) sizeHint(s + delta)
-  }
+  /** Gives a hint that the `result` of this builder is expected
+   *  to have the same size as the given collection, plus some delta.
+   *
+   *  This method provides a hint only if the collection has a known size,
+   *  as specified by the following pseudocode:
+   *
+   *  {{{
+   *    if (coll.knownSize != -1)
+   *      sizeHint(coll.knownSize + delta)
+   *  }}}
+   *
+   *  Some builder classes will optimize their representation based on the hint.
+   *  However, builder implementations are required to work correctly even if the hint is
+   *  wrong, i.e., if a different number of elements is added.
+   *
+   *  @param coll  the collection which serves as a hint for the result's size.
+   *  @param delta a correction to add to the `coll.size` to produce the size hint (zero if omitted).
+   */
+  final def sizeHint(coll: scala.collection.IterableOnce[_], delta: Int = 0): Unit =
+    coll.knownSize match {
+      case -1 =>
+      case sz => sizeHint(sz + delta)
+    }
 
   /** Gives a hint how many elements are expected to be added
     *  when the next `result` is called, together with an upper bound