Migration message and version cleanup

The @migration annotation can now be used like @deprecation.
Old syntax is still supported, but deprecated.

Improve wording and consistency of migration messages, migration
warnings also print the version in which the change occurred now.

Partially fixes SI-4990.

23 files changed, 69 insertions, 131 deletions

diff --git a/src/library/scala/annotation/migration.scala b/src/library/scala/annotation/migration.scala
index c2e392b807..8ab12a7c8e 100644
--- a/src/library/scala/annotation/migration.scala
+++ b/src/library/scala/annotation/migration.scala
@@ -14,15 +14,17 @@ package scala.annotation
  * reason or another retain the same name and type signature,
  * but some aspect of their behavior is different.  An illustrative
  * examples is Stack.iterator, which reversed from LIFO to FIFO
- * order between scala 2.7 and 2.8.
+ * order between Scala 2.7 and 2.8.
  *
- * The version numbers are to mark the scala major/minor release
- * version where the change took place.
+ * @param message A message describing the change, which is emitted
+ * by the compiler if the flag `-Xmigration` is set.
+ *
+ * @param changedIn The version, in which the behaviour change was
+ * introduced.
  *
  * @since 2.8
  */
-private[scala] final class migration(
-  majorVersion: Int,
-  minorVersion: Int,
-  message: String)
-extends annotation.StaticAnnotation {}
+ private[scala] final class migration(message: String, changedIn: String) extends annotation.StaticAnnotation {
+   @deprecated("Use the constructor taking two Strings instead.", "2.10")
+   def this(majorVersion: Int, minorVersion: Int, message: String) = this(message, majorVersion + "." + minorVersion)
+ }
\ No newline at end of file
diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala
index dc89bcf85d..122eec2d90 100644
--- a/src/library/scala/collection/GenTraversableLike.scala
+++ b/src/library/scala/collection/GenTraversableLike.scala
@@ -123,10 +123,7 @@ trait GenTraversableLike[+A, +Repr] extends GenTraversableOnce[A] with Paralleli
    *  @param bf      $bfinfo
    *  @return        collection with intermediate results
    */
-  @migration(2, 9,
-    "This scanRight definition has changed in 2.9.\n" +
-    "The previous behavior can be reproduced with scanRight.reverse."
-  )
+  @migration("The behavior of `scanRight` has changed. The previous behavior can be reproduced with scanRight.reverse.", "2.9.0")
   def scanRight[B, That](z: B)(op: (A, B) => B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
   /** Applies a function `f` to all elements of this $coll.
diff --git a/src/library/scala/collection/GenTraversableViewLike.scala b/src/library/scala/collection/GenTraversableViewLike.scala
index 9f7bbadfb2..78e0773fb0 100644
--- a/src/library/scala/collection/GenTraversableViewLike.scala
+++ b/src/library/scala/collection/GenTraversableViewLike.scala
@@ -12,8 +12,6 @@ package scala.collection
 import generic._
 import mutable.{ Builder, ArrayBuffer }
 import TraversableView.NoBuilder
-import annotation.migration
-
 
 
 trait GenTraversableViewLike[+A,
diff --git a/src/library/scala/collection/Iterator.scala b/src/library/scala/collection/Iterator.scala
index 7b780ba2e4..d46d215e0c 100644
--- a/src/library/scala/collection/Iterator.scala
+++ b/src/library/scala/collection/Iterator.scala
@@ -9,7 +9,7 @@
 package scala.collection
 
 import mutable.ArrayBuffer
-import annotation.{ tailrec, migration }
+import annotation.migration
 import immutable.Stream
 
 /** The `Iterator` object provides various functions for creating specialized iterators.
@@ -52,7 +52,7 @@ object Iterator {
 
   /** Creates iterator that produces the results of some element computation a number of times.
    *
-   *  @param   n  the number of elements returned by the iterator.
+   *  @param   len  the number of elements returned by the iterator.
    *  @param   elem the element computation
    *  @return  An iterator that produces the results of `n` evaluations of `elem`.
    */
@@ -66,7 +66,7 @@ object Iterator {
 
   /** Creates an iterator producing the values of a given function over a range of integer values starting from 0.
    *
-   *  @param  n   The number of elements returned by the iterator
+   *  @param  end The number of elements returned by the iterator
    *  @param  f   The function computing element values
    *  @return An iterator that produces the values `f(0), ..., f(n -1)`.
    */
@@ -410,10 +410,7 @@ trait Iterator[+A] extends TraversableOnce[A] {
   *  which `pf` is defined the image `pf(x)`.
   *  @note     Reuse: $consumesAndProducesIterator
   */
-  @migration(2, 8,
-    "This collect implementation bears no relationship to the one before 2.8.\n"+
-    "The previous behavior can be reproduced with toSeq."
-  )
+  @migration("`collect` has changed. The previous behavior can be reproduced with `toSeq`.", "2.8.0")
   def collect[B](pf: PartialFunction[A, B]): Iterator[B] = {
     val self = buffered
     new AbstractIterator[B] {
@@ -1033,9 +1030,9 @@ trait Iterator[+A] extends TraversableOnce[A] {
 
   /** Returns this iterator with patched values.
    *
-   *  @param from     The start index from which to patch
-   *  @param ps       The iterator of patch values
-   *  @param replaced The number of values in the original iterator that are replaced by the patch.
+   *  @param from       The start index from which to patch
+   *  @param patchElems The iterator of patch values
+   *  @param replaced   The number of values in the original iterator that are replaced by the patch.
    *  @note           Reuse: $consumesTwoAndProducesOneIterator
    */
   def patch[B >: A](from: Int, patchElems: Iterator[B], replaced: Int): Iterator[B] = new AbstractIterator[B] {
diff --git a/src/library/scala/collection/MapLike.scala b/src/library/scala/collection/MapLike.scala
index 1653a011d6..07116e99dd 100644
--- a/src/library/scala/collection/MapLike.scala
+++ b/src/library/scala/collection/MapLike.scala
@@ -182,14 +182,14 @@ self =>
    *
    *  @return the keys of this map as an iterable.
    */
-  @migration(2, 8, "As of 2.8, keys returns Iterable[A] rather than Iterator[A].")
+  @migration("`keys` returns `Iterable[A]` rather than `Iterator[A]`.", "2.8.0")
   def keys: Iterable[A] = keySet
 
   /** Collects all values of this map in an iterable collection.
    *
    *  @return the values of this map as an iterable.
    */
-  @migration(2, 8, "As of 2.8, values returns Iterable[B] rather than Iterator[B].")
+  @migration("`values` returns `Iterable[B]` rather than `Iterator[B]`.", "2.8.0")
   def values: Iterable[B] = new DefaultValuesIterable
 
   /** The implementation class of the iterable returned by `values`.
diff --git a/src/library/scala/collection/SetLike.scala b/src/library/scala/collection/SetLike.scala
index b4695363de..7293f3775c 100644
--- a/src/library/scala/collection/SetLike.scala
+++ b/src/library/scala/collection/SetLike.scala
@@ -89,7 +89,7 @@ self =>
   // note: this is only overridden here to add the migration annotation,
   // which I hope to turn into an Xlint style warning as the migration aspect
   // is not central to its importance.
-  @migration(2, 8, "Set.map now returns a Set, so it will discard duplicate values.")
+  @migration("Set.map now returns a Set, so it will discard duplicate values.", "2.8.0")
   override def map[B, That](f: A => B)(implicit bf: CanBuildFrom[This, B, That]): That = super.map(f)(bf)
 
   /** Tests if some element is contained in this set.
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index 4f0fec1de3..e2acc0b3e0 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -390,10 +390,7 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr]
     b.result
   }
 
-  @migration(2, 9,
-    "This scanRight definition has changed in 2.9.\n" +
-    "The previous behavior can be reproduced with scanRight.reverse."
-  )
+  @migration("The behavior of `scanRight` has changed. The previous behavior can be reproduced with scanRight.reverse.", "2.9.0")
   def scanRight[B, That](z: B)(op: (A, B) => B)(implicit bf: CanBuildFrom[Repr, B, That]): That = {
     var scanned = List(z)
     var acc = z
diff --git a/src/library/scala/collection/TraversableViewLike.scala b/src/library/scala/collection/TraversableViewLike.scala
index 8c67d841bc..60870cc835 100644
--- a/src/library/scala/collection/TraversableViewLike.scala
+++ b/src/library/scala/collection/TraversableViewLike.scala
@@ -185,10 +185,7 @@ trait TraversableViewLike[+A,
   override def scanLeft[B, That](z: B)(op: (B, A) => B)(implicit bf: CanBuildFrom[This, B, That]): That =
     newForced(thisSeq.scanLeft(z)(op)).asInstanceOf[That]
 
-  @migration(2, 9,
-    "This scanRight definition has changed in 2.9.\n" +
-    "The previous behavior can be reproduced with scanRight.reverse."
-  )
+  @migration("The behavior of `scanRight` has changed. The previous behavior can be reproduced with scanRight.reverse.", "2.9.0")
   override def scanRight[B, That](z: B)(op: (A, B) => B)(implicit bf: CanBuildFrom[This, B, That]): That =
     newForced(thisSeq.scanRight(z)(op)).asInstanceOf[That]
 
diff --git a/src/library/scala/collection/generic/GenericTraversableTemplate.scala b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
index 10cd3b5755..12c1a75c7a 100644
--- a/src/library/scala/collection/generic/GenericTraversableTemplate.scala
+++ b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
@@ -13,7 +13,6 @@ package generic
 
 import mutable.Builder
 import annotation.migration
-import annotation.bridge
 import annotation.unchecked.uncheckedVariance
 
 /** A template class for companion objects of ``regular`` collection classes
@@ -148,7 +147,7 @@ trait GenericTraversableTemplate[+A, +CC[X] <: GenTraversable[X]] extends HasNew
    *  @throws `IllegalArgumentException` if all collections in this $coll
    *          are not of the same size.
    */
-  @migration(2, 9, "As of 2.9, transpose throws an exception if collections are not uniformly sized.")
+  @migration("`transpose` throws an `IllegalArgumentException` if collections are not uniformly sized.", "2.9.0")
   def transpose[B](implicit asTraversable: A => /*<:<!!!*/ GenTraversableOnce[B]): CC[CC[B] @uncheckedVariance] = {
     if (isEmpty)
       return genericBuilder[CC[B]].result
diff --git a/src/library/scala/collection/mutable/BufferLike.scala b/src/library/scala/collection/mutable/BufferLike.scala
index acf26e59eb..1dc2fc27d5 100644
--- a/src/library/scala/collection/mutable/BufferLike.scala
+++ b/src/library/scala/collection/mutable/BufferLike.scala
@@ -152,7 +152,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
   def prepend(elems: A*) { prependAll(elems) }
 
   /** Prepends the elements contained in a traversable object to this buffer.
-   *  @param elems  the collection containing the elements to prepend.
+   *  @param xs  the collection containing the elements to prepend.
    */
   def prependAll(xs: TraversableOnce[A]) { xs ++=: this }
 
@@ -220,10 +220,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
    *  @param xs     the traversable object.
    *  @return       a new collection consisting of all the elements of this collection and `xs`.
    */
-  @migration(2, 8,
-    "As of 2.8, ++ always creates a new collection, even on Buffers.\n"+
-    "Use ++= instead if you intend to add by side effect to an existing collection.\n"
-  )
+  @migration("`++` creates a new buffer. Use `++=` to add an element from this buffer and return that buffer itself.", "2.8.0")
   def ++(xs: GenTraversableOnce[A]): This = clone() ++= xs.seq
 
   @bridge
@@ -234,10 +231,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
    *  @param elem  the element to remove.
    *  @return      a new collection consisting of all the elements of this collection except `elem`.
    */
-  @migration(2, 8,
-    "As of 2.8, - always creates a new collection, even on Buffers.\n"+
-    "Use -= instead if you intend to remove by side effect from an existing collection.\n"
-  )
+  @migration("`-` creates a new buffer. Use `-=` to remove an element from this buffer and return that buffer itself.", "2.8.0")
   override def -(elem: A): This = clone() -= elem
 
   /** Creates a new collection with all the elements of this collection except the two
@@ -249,10 +243,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
    *  @return      a new collection consisting of all the elements of this collection except
    *               `elem1`, `elem2` and those in `elems`.
    */
-  @migration(2, 8,
-    "As of 2.8, - always creates a new collection, even on Buffers.\n"+
-    "Use -= instead if you intend to remove by side effect from an existing collection.\n"
-  )
+  @migration("`-` creates a new buffer. Use `-=` to remove an element from this buffer and return that buffer itself.", "2.8.0")
   override def -(elem1: A, elem2: A, elems: A*): This = clone() -= elem1 -= elem2 --= elems
 
   /** Creates a new collection with all the elements of this collection except those
@@ -262,10 +253,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
    *  @return         a new collection with all the elements of this collection except
    *                  those in `xs`
    */
-  @migration(2, 8,
-    "As of 2.8, -- always creates a new collection, even on Buffers.\n"+
-    "Use --= instead if you intend to remove by side effect from an existing collection.\n"
-  )
+  @migration("`--` creates a new buffer. Use `--=` to remove an element from this buffer and return that buffer itself.", "2.8.0")
   override def --(xs: GenTraversableOnce[A]): This = clone() --= xs.seq
 
   @bridge def --(xs: TraversableOnce[A]): This = --(xs: GenTraversableOnce[A])
diff --git a/src/library/scala/collection/mutable/DoubleLinkedListLike.scala b/src/library/scala/collection/mutable/DoubleLinkedListLike.scala
index 7ad2f9558f..dfb70beeda 100644
--- a/src/library/scala/collection/mutable/DoubleLinkedListLike.scala
+++ b/src/library/scala/collection/mutable/DoubleLinkedListLike.scala
@@ -91,7 +91,7 @@ trait DoubleLinkedListLike[A, This <: Seq[A] with DoubleLinkedListLike[A, This]]
    *  current node, i.e. `this` node itself will still point "into" the list it
    *  was in.
    */
-  @migration(2, 9, "Double linked list now removes the current node from the list.")
+  @migration("Double linked list now removes the current node from the list.", "2.9.0")
   def remove(): Unit = if (nonEmpty) {
     next.prev = prev
     if (prev ne null) prev.next = next // because this could be the first node
diff --git a/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala b/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala
index 32fca1117c..3232179dbb 100644
--- a/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala
+++ b/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala
@@ -46,12 +46,12 @@ extends AbstractMap[A, B]
 
   override def keysIterator: Iterator[A] = imap.keysIterator
 
-  @migration(2, 8, "As of 2.8, keys returns Iterable[A] rather than Iterator[A].")
+  @migration("`keys` returns Iterable[A] rather than Iterator[A].", "2.8.0")
   override def keys: collection.Iterable[A] = imap.keys
 
   override def valuesIterator: Iterator[B] = imap.valuesIterator
 
-  @migration(2, 8, "As of 2.8, values returns Iterable[B] rather than Iterator[B].")
+  @migration("`values` returns Iterable[B] rather than Iterator[B].", "2.8.0")
   override def values: collection.Iterable[B] = imap.values
 
   def iterator: Iterator[(A, B)] = imap.iterator
diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala
index e4b1458e53..b08a4b7bc9 100644
--- a/src/library/scala/collection/mutable/MapLike.scala
+++ b/src/library/scala/collection/mutable/MapLike.scala
@@ -90,10 +90,7 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    *  @param kv    the key/value mapping to be added
    *  @return      a new map containing mappings of this map and the mapping `kv`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new map.  To add an element as a\n"+
-    "side effect to an existing map and return that map itself, use +=."
-  )
+  @migration("`+` creates a new map. Use `+=` to add an element to this map and return that map itself.", "2.8.0")
   def + [B1 >: B] (kv: (A, B1)): Map[A, B1] = clone().asInstanceOf[Map[A, B1]] += kv
 
   /** Creates a new map containing two or more key/value mappings and all the key/value
@@ -106,10 +103,7 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    *  @param elems the remaining elements to add.
    *  @return      a new map containing mappings of this map and two or more specified mappings.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new map.  To add an element as a\n"+
-    "side effect to an existing map and return that map itself, use +=."
-  )
+  @migration("`+` creates a new map. Use `+=` to add an element to this map and return that map itself.", "2.8.0")
   override def + [B1 >: B] (elem1: (A, B1), elem2: (A, B1), elems: (A, B1) *): Map[A, B1] =
     clone().asInstanceOf[Map[A, B1]] += elem1 += elem2 ++= elems
 
@@ -121,10 +115,7 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    *  @param xs     the traversable object.
    *  @return       a new map containing mappings of this map and those provided by `xs`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new map.  To add the elements as a\n"+
-    "side effect to an existing map and return that map itself, use ++=."
-  )
+  @migration("`++` creates a new map. Use `++=` to add an element to this map and return that map itself.", "2.8.0")
   override def ++[B1 >: B](xs: GenTraversableOnce[(A, B1)]): Map[A, B1] =
     clone().asInstanceOf[Map[A, B1]] ++= xs.seq
 
@@ -154,10 +145,7 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    *  @param    key the key to be removed
    *  @return   a new map with all the mappings of this map except that with a key `key`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new map.  To remove an element as a\n"+
-    "side effect to an existing map and return that map itself, use -=."
-  )
+  @migration("`-` creates a new map. Use `-=` to remove an element from this map and return that map itself.", "2.8.0")
   override def -(key: A): This = clone() -= key
 
   /** Removes all bindings from the map. After this operation has completed,
@@ -223,10 +211,7 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    *  @return      a new map containing all the mappings of this map except mappings
    *               with a key equal to `elem1`, `elem2` or any of `elems`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new map.  To remove an element as a\n"+
-    "side effect to an existing map and return that map itself, use -=."
-  )
+  @migration("`-` creates a new map. Use `-=` to remove an element from this map and return that map itself.", "2.8.0")
   override def -(elem1: A, elem2: A, elems: A*): This =
     clone() -= elem1 -= elem2 --= elems
 
@@ -237,10 +222,7 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    *  @return         a new map with all the key/value mappings of this map except mappings
    *                  with a key equal to a key from `xs`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new map.  To remove the elements as a\n"+
-    "side effect to an existing map and return that map itself, use --=."
-  )
+  @migration("`--` creates a new map. Use `--=` to remove an element from this map and return that map itself.", "2.8.0")
   override def --(xs: GenTraversableOnce[A]): This = clone() --= xs.seq
 
   @bridge def --(xs: TraversableOnce[A]): This =  --(xs: GenTraversableOnce[A])
diff --git a/src/library/scala/collection/mutable/PriorityQueue.scala b/src/library/scala/collection/mutable/PriorityQueue.scala
index 23a68c1d3e..381cb09e18 100644
--- a/src/library/scala/collection/mutable/PriorityQueue.scala
+++ b/src/library/scala/collection/mutable/PriorityQueue.scala
@@ -12,7 +12,7 @@ package scala.collection
 package mutable
 
 import generic._
-import annotation.{migration, bridge}
+import annotation.bridge
 
 /** This class implements priority queues using a heap.
  *  To prioritize elements of type A there must be an implicit
diff --git a/src/library/scala/collection/mutable/SetLike.scala b/src/library/scala/collection/mutable/SetLike.scala
index c5eeb1ae7f..5e201d9959 100644
--- a/src/library/scala/collection/mutable/SetLike.scala
+++ b/src/library/scala/collection/mutable/SetLike.scala
@@ -141,10 +141,7 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
    *  @param elem  the element to add.
    *  @return      a new set consisting of elements of this set and `elem`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new set.  To add an element as a\n"+
-    "side effect to an existing set and return that set itself, use +=."
-  )
+  @migration("`+` creates a new set. Use `+=` to add an element to this set and return that set itself.", "2.8.0")
   override def + (elem: A): This = clone() += elem
 
   /** Creates a new set consisting of all the elements of this set and two or more
@@ -158,10 +155,7 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
    *  @return      a new set consisting of all the elements of this set, `elem1`,
    *               `elem2` and those in `elems`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new set.  To add the elements as a\n"+
-    "side effect to an existing set and return that set itself, use +=."
-  )
+  @migration("`+` creates a new set. Use `+=` to add an element to this set and return that set itself.", "2.8.0")
   override def + (elem1: A, elem2: A, elems: A*): This =
     clone() += elem1 += elem2 ++= elems
 
@@ -173,10 +167,7 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
    *  @param xs        the traversable object.
    *  @return          a new set consisting of elements of this set and those in `xs`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new set.  To add the elements as a\n"+
-    "side effect to an existing set and return that set itself, use ++=."
-  )
+  @migration("`++` creates a new set. Use `++=` to add elements to this set and return that set itself.", "2.8.0")
   override def ++(xs: GenTraversableOnce[A]): This = clone() ++= xs.seq
 
   @bridge def ++(xs: TraversableOnce[A]): This = ++(xs: GenTraversableOnce[A])
@@ -186,10 +177,7 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
    *  @param elem  the element to remove.
    *  @return      a new set consisting of all the elements of this set except `elem`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new set.  To remove the element as a\n"+
-    "side effect to an existing set and return that set itself, use -=."
-  )
+  @migration("`-` creates a new set. Use `-=` to remove an element from this set and return that set itself.", "2.8.0")
   override def -(elem: A): This = clone() -= elem
 
   /** Creates a new set consisting of all the elements of this set except the two
@@ -201,10 +189,7 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
    *  @return      a new set consisting of all the elements of this set except
    *               `elem1`, `elem2` and `elems`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new set.  To remove the elements as a\n"+
-    "side effect to an existing set and return that set itself, use -=."
-  )
+  @migration("`-` creates a new set. Use `-=` to remove an element from this set and return that set itself.", "2.8.0")
   override def -(elem1: A, elem2: A, elems: A*): This =
     clone() -= elem1 -= elem2 --= elems
 
@@ -215,10 +200,7 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
    *  @return         a new set consisting of all the elements of this set except
    *                  elements from `xs`.
    */
-  @migration(2, 8,
-    "As of 2.8, this operation creates a new set.  To remove the elements as a\n"+
-    "side effect to an existing set and return that set itself, use --=."
-  )
+  @migration("`--` creates a new set. Use `--=` to remove elements from this set and return that set itself.", "2.8.0")
   override def --(xs: GenTraversableOnce[A]): This = clone() --= xs.seq
 
   @bridge def --(xs: TraversableOnce[A]): This = --(xs: GenTraversableOnce[A])
diff --git a/src/library/scala/collection/mutable/Stack.scala b/src/library/scala/collection/mutable/Stack.scala
index ffac3b78b7..8fad131009 100644
--- a/src/library/scala/collection/mutable/Stack.scala
+++ b/src/library/scala/collection/mutable/Stack.scala
@@ -156,17 +156,17 @@ extends AbstractSeq[A]
    *
    *  @return an iterator over all stack elements.
    */
-  @migration(2, 8, "Stack iterator and foreach now traverse in FIFO order.")
+  @migration("`iterator` traverses in FIFO order.", "2.8.0")
   override def iterator: Iterator[A] = elems.iterator
 
   /** Creates a list of all stack elements in LIFO order.
    *
    *  @return the created list.
    */
-  @migration(2, 8, "Stack iterator and foreach now traverse in FIFO order.")
+  @migration("`toList` traverses in FIFO order.", "2.8.0")
   override def toList: List[A] = elems
 
-  @migration(2, 8, "Stack iterator and foreach now traverse in FIFO order.")
+  @migration("`foreach` traverses in FIFO order.", "2.8.0")
   override def foreach[U](f: A => U): Unit = super.foreach(f)
 
   /** This method clones the stack.
diff --git a/src/library/scala/collection/mutable/StringBuilder.scala b/src/library/scala/collection/mutable/StringBuilder.scala
index 603086d209..d9ad58f054 100644
--- a/src/library/scala/collection/mutable/StringBuilder.scala
+++ b/src/library/scala/collection/mutable/StringBuilder.scala
@@ -403,7 +403,7 @@ final class StringBuilder(private val underlying: JavaStringBuilder)
    *
    *  @return   the reversed StringBuilder
    */
-  @migration(2, 8, "Since 2.8 reverse returns a new instance.  Use 'reverseContents' to update in place.")
+  @migration("`reverse` returns a new instance.  Use `reverseContents` to update in place and return that StringBuilder itself.", "2.8.0")
   override def reverse: StringBuilder = new StringBuilder(new JavaStringBuilder(underlying) reverse)
 
   override def clone(): StringBuilder = new StringBuilder(new JavaStringBuilder(underlying))
diff --git a/src/library/scala/collection/mutable/SynchronizedMap.scala b/src/library/scala/collection/mutable/SynchronizedMap.scala
index 8b2c6faa41..6e3ae13ada 100644
--- a/src/library/scala/collection/mutable/SynchronizedMap.scala
+++ b/src/library/scala/collection/mutable/SynchronizedMap.scala
@@ -40,14 +40,14 @@ trait SynchronizedMap[A, B] extends Map[A, B] {
   override def getOrElseUpdate(key: A, default: => B): B = synchronized { super.getOrElseUpdate(key, default) }
   override def transform(f: (A, B) => B): this.type = synchronized[this.type] { super.transform(f) }
   override def retain(p: (A, B) => Boolean): this.type = synchronized[this.type] { super.retain(p) }
-  @migration(2, 8, "As of 2.8, values returns Iterable[B] rather than Iterator[B].")
+  @migration("`values` returns `Iterable[B]` rather than `Iterator[B]`.", "2.8.0")
   override def values: collection.Iterable[B] = synchronized { super.values }
   override def valuesIterator: Iterator[B] = synchronized { super.valuesIterator }
   override def clone(): Self = synchronized { super.clone() }
   override def foreach[U](f: ((A, B)) => U) = synchronized { super.foreach(f) }
   override def apply(key: A): B = synchronized { super.apply(key) }
   override def keySet: collection.Set[A] = synchronized { super.keySet }
-  @migration(2, 8, "As of 2.8, keys returns Iterable[A] rather than Iterator[A].")
+  @migration("`keys` returns `Iterable[A]` rather than `Iterator[A]`.", "2.8.0")
   override def keys: collection.Iterable[A] = synchronized { super.keys }
   override def keysIterator: Iterator[A] = synchronized { super.keysIterator }
   override def isEmpty: Boolean = synchronized { super.isEmpty }
diff --git a/src/library/scala/io/Codec.scala b/src/library/scala/io/Codec.scala
index 487f9c7b87..8533ed493f 100644
--- a/src/library/scala/io/Codec.scala
+++ b/src/library/scala/io/Codec.scala
@@ -97,7 +97,7 @@ object Codec extends LowPriorityCodecImplicits {
     new Codec(decoder.charset()) { override def decoder = _decoder }
   }
 
-  @migration(2, 9, "This method was previously misnamed `toUTF8`. Converts from Array[Byte] to Array[Char].")
+  @migration("This method was previously misnamed `toUTF8`. Converts from Array[Byte] to Array[Char].", "2.9.0")
   def fromUTF8(bytes: Array[Byte]): Array[Char] = {
     val bbuffer = java.nio.ByteBuffer wrap bytes
     val cbuffer = UTF8.charSet decode bbuffer
@@ -107,7 +107,7 @@ object Codec extends LowPriorityCodecImplicits {
     chars
   }
 
-  @migration(2, 9, "This method was previously misnamed `fromUTF8`. Converts from character sequence to Array[Byte].")
+  @migration("This method was previously misnamed `fromUTF8`. Converts from character sequence to Array[Byte].", "2.9.0")
   def toUTF8(cs: CharSequence): Array[Byte] = {
     val cbuffer = java.nio.CharBuffer wrap cs
     val bbuffer = UTF8.charSet encode cbuffer
diff --git a/src/library/scala/math/BigDecimal.scala b/src/library/scala/math/BigDecimal.scala
index 553fb08c18..497de92c80 100644
--- a/src/library/scala/math/BigDecimal.scala
+++ b/src/library/scala/math/BigDecimal.scala
@@ -13,7 +13,6 @@ import java.{ lang => jl }
 import java.math.{ MathContext, BigDecimal => BigDec }
 import scala.collection.immutable.NumericRange
 
-import annotation.migration
 
 /**
  *  @author  Stephane Micheloud
diff --git a/src/library/scala/math/Ordered.scala b/src/library/scala/math/Ordered.scala
index b67146942f..53d618db63 100644
--- a/src/library/scala/math/Ordered.scala
+++ b/src/library/scala/math/Ordered.scala
@@ -58,11 +58,11 @@ trait Ordered[A] extends java.lang.Comparable[A] {
    *
    * Returns `x` where:
    *
-   *   - `x < 0` when `this > that`
+   *   - `x < 0` when `this < that`
    *
    *   - `x == 0` when `this == that`
    *
-   *   - `x < 0` when  `this > that`
+   *   - `x > 0` when  `this > that`
    *
    */
   def compare(that: A): Int
diff --git a/src/library/scala/math/Ordering.scala b/src/library/scala/math/Ordering.scala
index b23165154c..d007ae3780 100644
--- a/src/library/scala/math/Ordering.scala
+++ b/src/library/scala/math/Ordering.scala
@@ -10,7 +10,7 @@ package scala.math
 
 import java.util.Comparator
 
-/** Ordering is trait whose instances each represent a strategy for sorting
+/** Ordering is a trait whose instances each represent a strategy for sorting
   * instances of a type.
   *
   * Ordering's companion object defines many implicit objects to deal with
diff --git a/src/library/scala/util/parsing/combinator/Parsers.scala b/src/library/scala/util/parsing/combinator/Parsers.scala
index 751539243b..4004a01ad9 100644
--- a/src/library/scala/util/parsing/combinator/Parsers.scala
+++ b/src/library/scala/util/parsing/combinator/Parsers.scala
@@ -89,14 +89,14 @@ trait Parsers {
   sealed abstract class ParseResult[+T] {
     /** Functional composition of ParseResults.
      *
-     * @param `f` the function to be lifted over this result
+     * @param f the function to be lifted over this result
      * @return `f` applied to the result of this `ParseResult`, packaged up as a new `ParseResult`
      */
     def map[U](f: T => U): ParseResult[U]
 
     /** Partial functional composition of ParseResults.
      *
-     * @param `f` the partial function to be lifted over this result
+     * @param f the partial function to be lifted over this result
      * @param error a function that takes the same argument as `f` and
      *        produces an error message to explain why `f` wasn't applicable
      *        (it is called when this is the case)
@@ -240,7 +240,7 @@ trait Parsers {
 
     // no filter yet, dealing with zero is tricky!
 
-    @migration(2, 9, "As of 2.9, the call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.")
+    @migration("The call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.", "2.9.0")
     def append[U >: T](p0: => Parser[U]): Parser[U] = { lazy val p = p0 // lazy argument
       Parser{ in => this(in) append p(in)}
     }
@@ -259,7 +259,7 @@ trait Parsers {
      *         but easier to pattern match on) that contains the result of `p` and
      *         that of `q`. The resulting parser fails if either `p` or `q` fails.
      */
-    @migration(2, 9, "As of 2.9, the call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.")
+    @migration("The call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.", "2.9.0")
     def ~ [U](q: => Parser[U]): Parser[~[T, U]] = { lazy val p = q // lazy argument
       (for(a <- this; b <- p) yield new ~(a,b)).named("~")
     }
@@ -272,7 +272,7 @@ trait Parsers {
      *        succeeds -- evaluated at most once, and only when necessary.
      * @return a `Parser` that -- on success -- returns the result of `q`.
      */
-    @migration(2, 9, "As of 2.9, the call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.")
+    @migration("The call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.", "2.9.0")
     def ~> [U](q: => Parser[U]): Parser[U] = { lazy val p = q // lazy argument
       (for(a <- this; b <- p) yield b).named("~>")
     }
@@ -287,7 +287,7 @@ trait Parsers {
      * @param q a parser that will be executed after `p` (this parser) succeeds -- evaluated at most once, and only when necessary
      * @return a `Parser` that -- on success -- returns the result of `p`.
      */
-    @migration(2, 9, "As of 2.9, the call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.")
+    @migration("The call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.", "2.9.0")
     def <~ [U](q: => Parser[U]): Parser[T] = { lazy val p = q // lazy argument
       (for(a <- this; b <- p) yield a).named("<~")
     }
@@ -302,7 +302,7 @@ trait Parsers {
      *  `p ~! q` succeeds if `p` succeeds and `q` succeeds on the input left over by `p`.
      *   In case of failure, no back-tracking is performed (in an earlier parser produced by the `|` combinator).
      *
-     * @param q a parser that will be executed after `p` (this parser) succeeds
+     * @param p a parser that will be executed after `p` (this parser) succeeds
      * @return a `Parser` that -- on success -- returns a `~` (like a Pair, but easier to pattern match on)
      *         that contains the result of `p` and that of `q`.
      *         The resulting parser fails if either `p` or `q` fails, this failure is fatal.
@@ -332,7 +332,7 @@ trait Parsers {
      * @param q0 a parser that accepts if p consumes less characters. -- evaluated at most once, and only when necessary
      * @return a `Parser` that returns the result of the parser consuming the most characters (out of `p` and `q`).
      */
-    @migration(2, 9, "As of 2.9, the call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.")
+    @migration("The call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.", "2.9.0")
     def ||| [U >: T](q0: => Parser[U]): Parser[U] = new Parser[U] {
       lazy val q = q0 // lazy argument
       def apply(in: Input) = {
@@ -367,7 +367,7 @@ trait Parsers {
      * @param v The new result for the parser, evaluated at most once (if `p` succeeds), not evaluated at all if `p` fails.
      * @return a parser that has the same behaviour as the current parser, but whose successful result is `v`
      */
-    @migration(2, 9, "As of 2.9, the call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.")
+    @migration("The call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.", "2.9.0")
     def ^^^ [U](v: => U): Parser[U] =  new Parser[U] {
       lazy val v0 = v // lazy argument
       def apply(in: Input) = Parser.this(in) map (x => v0)
@@ -706,7 +706,7 @@ trait Parsers {
    * @return A parser that returns a list of results produced by first applying `f` and then
    *         repeatedly `p` to the input (it only succeeds if `f` matches).
    */
-  @migration(2, 9, "As of 2.9, the p0 call-by-name arguments is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.")
+  @migration("The `p0` call-by-name arguments is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.", "2.9.0")
   def rep1[T](first: => Parser[T], p0: => Parser[T]): Parser[List[T]] = Parser { in =>
     lazy val p = p0 // lazy argument
     val elems = new ListBuffer[T]
@@ -733,9 +733,9 @@ trait Parsers {
    *  `repN(n, p)` uses `p` exactly `n` time to parse the input
    *  (the result is a `List` of the `n` consecutive results of `p`).
    *
-   * @param p a `Parser` that is to be applied successively to the input
-   * @param n the exact number of times `p` must succeed
-   * @return A parser that returns a list of results produced by repeatedly applying `p` to the input
+   * @param p   a `Parser` that is to be applied successively to the input
+   * @param num the exact number of times `p` must succeed
+   * @return    A parser that returns a list of results produced by repeatedly applying `p` to the input
    *        (and that only succeeds if `p` matches exactly `n` times).
    */
   def repN[T](num: Int, p: => Parser[T]): Parser[List[T]] =