Migration rework #1:

 - The @migration annotation can now be used like @Deprecation, old syntax is still supported, but deprecated.
 - Improved the wording and the consistency of most migration messages, migration warnings now also show the version the change occurred.
 - Adjusted test.
 - Partially fixes SI-4990.

Author: soc

src/compiler/scala/reflect/internal/Symbols.scala

@@ -494,8 +494,8 @@ trait Symbols extends api.Symbols { self: SymbolTable =>
     // string.  So this needs attention.  For now the fact that migration is
     // private[scala] ought to provide enough protection.
     def hasMigrationAnnotation = hasAnnotation(MigrationAnnotationClass)
-    def migrationMessage    = getAnnotation(MigrationAnnotationClass) flatMap { _.stringArg(2) }
-    def migrationVersion    = getAnnotation(MigrationAnnotationClass) map { version => version.intArg(0).get + "." + version.intArg(1).get }
+    def migrationMessage    = getAnnotation(MigrationAnnotationClass) flatMap { _.stringArg(0) }
+    def migrationVersion    = getAnnotation(MigrationAnnotationClass) flatMap { _.stringArg(1) }
     def elisionLevel        = getAnnotation(ElidableMethodClass) flatMap { _.intArg(0) }
     def implicitNotFoundMsg = getAnnotation(ImplicitNotFoundClass) flatMap { _.stringArg(0) }
 

src/compiler/scala/tools/nsc/typechecker/RefChecks.scala

@@ -1273,8 +1273,10 @@ abstract class RefChecks extends InfoTransform with reflect.internal.transform.R
      *  indicating it has changed semantics between versions.
      */
     private def checkMigration(sym: Symbol, pos: Position) = {
-      for (msg <- sym.migrationMessage)
-        unit.warning(pos, sym.fullLocationString + " has changed semantics:\n" + msg)
+      if (sym.hasMigrationAnnotation)
+        unit.warning(pos, "%s has changed semantics in version %s:\n%s".format(
+          sym.fullLocationString, sym.migrationVersion.get, sym.migrationMessage.get)
+        )
     }
 
     private def lessAccessible(otherSym: Symbol, memberSym: Symbol): Boolean = (

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)
+ }

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")
   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.

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,

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")
   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] {

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")
   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")
   def values: Iterable[B] = new DefaultValuesIterable
 
   /** The implementation class of the iterable returned by `values`.

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")
   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.

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")
   def scanRight[B, That](z: B)(op: (A, B) => B)(implicit bf: CanBuildFrom[Repr, B, That]): That = {
     var scanned = List(z)
     var acc = z

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")
   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]