docs for breakout and no-arg apply in canbuildfrom

2 files changed, 6 insertions, 2 deletions

diff --git a/src/library/scala/collection/generic/CanBuildFrom.scala b/src/library/scala/collection/generic/CanBuildFrom.scala
index 9bc5914168..4136b88cf5 100644
--- a/src/library/scala/collection/generic/CanBuildFrom.scala
+++ b/src/library/scala/collection/generic/CanBuildFrom.scala
@@ -37,8 +37,10 @@ trait CanBuildFrom[-From, -Elem, +To] {
    */
   def apply(from: From): Builder[Elem, To]
 
-  /** Creates a new builder from scratch
+  /** Creates a new builder from scratch.
+   *
    *  @return a builder for collections of type `To` with element type `Elem`.
+   *  @see scala.collection.breakOut
    */
   def apply(): Builder[Elem, To]
 }
diff --git a/src/library/scala/collection/package.scala b/src/library/scala/collection/package.scala
index d5161a0f1a..bcd2fb5d38 100644
--- a/src/library/scala/collection/package.scala
+++ b/src/library/scala/collection/package.scala
@@ -3,8 +3,10 @@ package scala
 package object collection {
   import scala.collection.generic.CanBuildFrom // can't refer to CanBuild here
 
+  /** Provides a CanBuildFrom instance that builds a specific target collection (`To') irrespective of the original collection (`From').
+   */
   def breakOut[From, T, To](implicit b : CanBuildFrom[Nothing, T, To]) =
-    new CanBuildFrom[From, T, To] {
+    new CanBuildFrom[From, T, To] { // TODO: could we just return b instead?
       def apply(from: From) = b.apply() ; def apply() = b.apply()
     }
 }
\ No newline at end of file