Improve doc of dropWhile

Author: som-snytt

library/src/scala/collection/Iterable.scala

@@ -420,12 +420,14 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
   def withFilter(p: A => Boolean): collection.WithFilter[A, CC] = new IterableOps.WithFilter(this, p)
 
   /** A pair of, first, all elements that satisfy predicate `p` and, second,
-    *  all elements that do not. Interesting because it splits a collection in two.
-    *
-    *  The default implementation provided here needs to traverse the collection twice.
-    *  Strict collections have an overridden version of `partition` in `StrictOptimizedIterableOps`,
-    *  which requires only a single traversal.
-    */
+   *  all elements that do not.
+   *
+   *  The two $coll correspond to the result of [[filter]] and [[filterNot]], respectively.
+   *
+   *  The default implementation provided here needs to traverse the collection twice.
+   *  Strict collections have an overridden version of `partition` in `StrictOptimizedIterableOps`,
+   *  which requires only a single traversal.
+   */
   def partition(p: A => Boolean): (C, C) = {
     val first = new View.Filter(this, p, false)
     val second = new View.Filter(this, p, true)

library/src/scala/collection/IterableOnce.scala

@@ -357,6 +357,24 @@ trait IterableOnceOps[+A, +CC[_], +C] extends Any { this: IterableOnce[A] =>
   def take(n: Int): C
 
   /** Takes longest prefix of elements that satisfy a predicate.
+   *
+   *  The matching prefix starts with the first element of this $coll,
+   *  and the element following the prefix is the first element that
+   *  does not satisfy the predicate. The matching prefix may empty,
+   *  so that this method returns an empty $coll.
+   *
+   *  Example:
+   *
+   *  {{{
+   *      scala> List(1, 2, 3, 100, 4).takeWhile(n => n < 10)
+   *      val res0: List[Int] = List(1, 2, 3)
+   *
+   *      scala> List(1, 2, 3, 100, 4).takeWhile(n => n == 0)
+   *      val res1: List[Int] = List()
+   *  }}}
+   *
+   *  Use [[span]] to obtain both the prefix and suffix.
+   *  Use [[filter]] to retain only those elements from the entire $coll that satisfy the predicate.
    *  $orderDependent
    *  @param   p  The predicate used to test elements.
    *  @return  the longest prefix of this $coll whose elements all satisfy
@@ -374,6 +392,25 @@ trait IterableOnceOps[+A, +CC[_], +C] extends Any { this: IterableOnce[A] =>
   def drop(n: Int): C
 
   /** Drops longest prefix of elements that satisfy a predicate.
+   *
+   *  The matching prefix starts with the first element of this $coll,
+   *  and the element following the prefix is the first element that
+   *  does not satisfy the predicate. The matching prefix may empty,
+   *  so that this method returns the entire $coll.
+   *
+   *  Example:
+   *
+   *  {{{
+   *      scala> List(1, 2, 3, 100, 4).dropWhile(n => n < 10)
+   *      val res0: List[Int] = List(100, 4)
+   *
+   *      scala> List(1, 2, 3, 100, 4).dropWhile(n => n == 0)
+   *      val res1: List[Int] = List(1, 2, 3, 100, 4)
+   *  }}}
+   *
+   *  Use [[span]] to obtain both the prefix and suffix.
+   *  Use [[filterNot]] to drop all elements that satisfy the predicate.
+   *
    *  $orderDependent
    *  @param   p  The predicate used to test elements.
    *  @return  the longest suffix of this $coll whose first element

library/src/scala/language.scala

@@ -104,8 +104,8 @@ object language {
    *  non-implicit parameter. Examples:
    *
    *  {{{
-   *     implicit def intToString(i: Int): String = s"$i"
-   *     implicit val conv: Int => String = i => s"$i"
+   *     implicit def intToString(i: Int): String = s"\$i"
+   *     implicit val conv: Int => String = i => s"\$i"
    *     implicit val numerals: List[String] = List("zero", "one", "two", "three")
    *     implicit val strlen: String => Int = _.length
    *     implicit def listToInt[T](xs: List[T])(implicit f: T => Int): Int = xs.map(f).sum