Fixes #4478.

src/library/scala/Enumeration.scala

@@ -112,14 +112,7 @@ abstract class Enumeration(initial: Int, names: String*) extends Serializable {
   /** Returns a Value from this Enumeration whose name matches 
    * the argument <var>s</var>.
    *
-   * You can pass a String* set of names to the constructor, or
-   * initialize each Enumeration with Value(String). Otherwise, the
-   * names are determined automatically through reflection.
-   *
-   * Note the change here wrt 2.7 is intentional. You should know whether
-   * a name is in an Enumeration beforehand. If not, just use find on
-   * values.
-   *
+   * @see `values.find` if it is unknown whether the Enumeration contains the Value.
    * @param  s an Enumeration name
    * @return   the Value of this Enumeration if its name matches <var>s</var>
    * @throws   java.util.NoSuchElementException if no Value with a matching
@@ -130,8 +123,7 @@ abstract class Enumeration(initial: Int, names: String*) extends Serializable {
   /** Creates a fresh value, part of this enumeration. */
   protected final def Value: Value = Value(nextId)
 
-  /** Creates a fresh value, part of this enumeration, identified by the integer
-   *  `i`.
+  /** Creates a fresh value, part of this enumeration, identified by the integer `i`.
    *
    *  @param i An integer that identifies this value at run-time. It must be
    *           unique amongst all values of the enumeration.

src/library/scala/collection/GenSeqLike.scala

@@ -107,8 +107,8 @@ private[collection] trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr]
    *
    *  @param   elem   the element value to search for.
    *  @tparam  B      the type of the element `elem`. 
-   *  @return  the index of the first element of this $coll that is equal (wrt `==`)
-   *           to `elem`, or `-1`, if none exists.
+   *  @return  the index of the first element of this $coll that is equal
+   *           to `elem` (as determined by `==`), or `-1`, if none exists.
    *
    *  @usecase def indexOf(elem: A): Int
    */
@@ -121,8 +121,8 @@ private[collection] trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr]
    *  @param   elem   the element value to search for.
    *  @tparam  B      the type of the element `elem`. 
    *  @param   from   the start index
-   *  @return  the index `>= from` of the first element of this $coll that is equal (wrt `==`)
-   *           to `elem`, or `-1`, if none exists.
+   *  @return  the index `>= from` of the first element of this $coll that is equal
++   *           to `elem` (as determined by `==`), or `-1`, if none exists.
    *
    *  @usecase def indexOf(elem: A, from: Int): Int
    */
@@ -134,8 +134,8 @@ private[collection] trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr]
    *
    *  @param   elem   the element value to search for.
    *  @tparam  B      the type of the element `elem`. 
-   *  @return  the index of the last element of this $coll that is equal (wrt `==`)
-   *           to `elem`, or `-1`, if none exists.
+   *  @return  the index of the last element of this $coll that is equal
+   *           to `elem` (as determined by `==`), or `-1`, if none exists.
    *
    *  @usecase def lastIndexOf(elem: A): Int
    */
@@ -146,8 +146,8 @@ private[collection] trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr]
    *  @param   elem   the element value to search for.
    *  @param   end    the end index.
    *  @tparam  B      the type of the element `elem`. 
-   *  @return  the index `<= end` of the last element of this $coll that is equal (wrt `==`)
-   *           to `elem`, or `-1`, if none exists.
+   *  @return  the index `<= end` of the last element of this $coll that is equal
+   *           to `elem` (as determined by `==`), or `-1`, if none exists.
    *
    *  @usecase def lastIndexOf(elem: A, end: Int): Int
    */

src/library/scala/collection/Iterator.scala

@@ -680,8 +680,8 @@ trait Iterator[+A] extends TraversableOnce[A] {
    *  $mayNotTerminateInf
    *
    *  @param elem  the element to test.
-   *  @return     `true` if this iterator produces some value that is
-   *               is equal (wrt `==`) to `elem`, `false` otherwise.
+   *  @return      `true` if this iterator produces some value that
+   *               is equal to `elem` (as determined by `==`), `false` otherwise.
    */
   def contains(elem: Any): Boolean = exists(_ == elem)
 

src/library/scala/collection/SeqLike.scala

@@ -373,8 +373,8 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr]
    *  $mayNotTerminateInf
    *
    *  @param elem  the element to test.
-   *  @return     `true` if this $coll has an element that is
-   *               is equal (wrt `==`) to `elem`, `false` otherwise.
+   *  @return     `true` if this $coll has an element that is equal
+   *              (as determined by `==`) to `elem`, `false` otherwise.
    */
   def contains(elem: Any): Boolean = exists (_ == elem)
 
@@ -539,7 +539,7 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr]
   /** Sorts this $coll according to a comparison function.
    *  $willNotTerminateInf
    * 
-   *  The sort is stable. That is, elements that are equal wrt `lt` appear in the
+   *  The sort is stable. That is, elements that are equal (as determined by `lt`) appear in the
    *  same order in the sorted sequence as in the original.
    *
    *  @param  lt  the comparison function which tests whether
@@ -578,7 +578,7 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr]
 
   /** Sorts this $coll according to an Ordering.
    * 
-   *  The sort is stable. That is, elements that are equal wrt `lt` appear in the
+   *  The sort is stable. That is, elements that are equal (as determined by `lt`) appear in the
    *  same order in the sorted sequence as in the original.
    *
    *  @see scala.math.Ordering

src/library/scala/collection/immutable/List.scala

@@ -97,7 +97,7 @@ sealed abstract class List[+A] extends LinearSeq[A]
 
   /** Builds a new list by applying a function to all elements of this list.
    *  Like `xs map f`, but returns `xs` unchanged if function
-   *  `f` maps all elements to themselves (wrt eq).
+   *  `f` maps all elements to themselves (as determined by `eq`).
    * 
    *  @param f      the function to apply to each element.
    *  @tparam B     the element type of the returned collection.
@@ -286,20 +286,15 @@ sealed abstract class List[+A] extends LinearSeq[A]
   @deprecated("use `distinct' instead", "2.8.0")
   def removeDuplicates: List[A] = distinct
 
-  /** <p>
-   *    Sort the list according to the comparison function
-   *    `lt(e1: a, e2: a) =&gt; Boolean`,
-   *    which should be true iff `e1` precedes     
-   *    `e2` in the desired ordering.
-   *  !!! todo: move sorting to IterableLike
-   *  </p>
+  /** Sort the list according to the comparison function `lt(e1: a, e2: a) => Boolean`,
+   *  which should be true iff `e1` precedes `e2` in the desired ordering.
    *
-   *  @param lt the comparison function
+   *  @param    lt the comparison function
    *  @return   a list sorted according to the comparison function
-   *            `lt(e1: a, e2: a) =&gt; Boolean`.
+   *            `lt(e1: a, e2: a) => Boolean`.
    *  @example <pre>
    *    List("Steve", "Tom", "John", "Bob")
-   *      .sort((e1, e2) => (e1 compareTo e2) &lt; 0) =
+   *      .sort((e1, e2) => (e1 compareTo e2) < 0) =
    *    List("Bob", "John", "Steve", "Tom")</pre>
    */
   @deprecated("use `sortWith' instead", "2.8.0")

src/library/scala/collection/immutable/Stream.scala

@@ -447,8 +447,7 @@ self =>
     these
   }
 
-  /** Builds a new stream from this stream in which any duplicates (wrt to ==) removed.
-   *  Among duplicate elements, only the first one is retained in the result stream
+  /** Builds a new stream from this stream in which any duplicates (as determined by `==`) removed.   *  Among duplicate elements, only the first one is retained in the result stream
    */
   override def distinct: Stream[A] =
     if (isEmpty) this

src/library/scala/util/parsing/ast/Binders.scala

@@ -76,8 +76,7 @@ trait Mappable {
  */
 trait Binders extends AbstractSyntax with Mappable {
   /** A `Scope' keeps track of one or more syntactic elements that represent bound names.
-   * The elements it contains share the same scope and must all be distinct (wrt. ==)
-   *
+   * The elements it contains share the same scope and must all be distinct, as determined by `=='.   *
    * A `NameElement' `n' in the AST that is conceptually bound by a `Scope' `s', is replaced by a 
    * `BoundElement(n, s)'. (For example, in `val x:Int=x+1', the first `x' is modelled by a
    * Scope `s' that contains `x' and the second `x' is represented by a `BoundElement(`x', s)')

src/library/scala/util/parsing/input/OffsetPosition.scala

@@ -60,8 +60,8 @@ case class OffsetPosition(source: java.lang.CharSequence, offset: Int) extends P
    * and then -- if necessary -- using the columns to break a tie.
    *
    * @param `that' a `Position' to compare to this `Position'
-   * @return true if this position's line or (in case of a tie wrt. line numbers)
-   *         its column is smaller than the corresponding components of `that'
+   * @return true if this position's line number or (in case of equal line numbers)
+   *         column is smaller than the corresponding components of `that'hat'
    */
   override def <(that: Position) = that match {
     case OffsetPosition(_, that_offset) =>

src/library/scala/util/parsing/input/Position.scala

@@ -59,8 +59,8 @@ trait Position {
    * and then -- if necessary -- using the columns to break a tie.
    *
    * @param `that' a `Position' to compare to this `Position'
-   * @return true if this position's line or (in case of a tie wrt. line numbers)
-   *         its column is smaller than the corresponding components of `that'
+   * @return true if this position's line number or (in case of equal line numbers)
+   *         column is smaller than the corresponding components of `that'
    */
   def <(that: Position) = {
     this.line < that.line ||