Merge remote-tracking branch 'scala/2.10.x'

Conflicts:
	build.number
	src/reflect/scala/reflect/internal/Types.scala

14 files changed, 102 insertions, 43 deletions

diff --git a/src/library/rootdoc.txt b/src/library/rootdoc.txt
index da27a0084b..0722d808bf 100644
--- a/src/library/rootdoc.txt
+++ b/src/library/rootdoc.txt
@@ -4,24 +4,25 @@ This is the documentation for the Scala standard library.
 
 The [[scala]] package contains core types.
 
-scala.[[scala.collection]] and its subpackages contain a collections framework with higher-order functions for manipulation. Both [[scala.collection.immutable]] and [[scala.collection.mutable]] data structures are available, with immutable as the default. The [[scala.collection.parallel]] collections provide automatic parallel operation.
+[[scala.collection `scala.collection`]] and its subpackages contain a collections framework with higher-order functions for manipulation. Both [[scala.collection.immutable `scala.collection.immutable`]] and [[scala.collection.mutable `scala.collection.mutable`]] data structures are available, with immutable as the default. The [[scala.collection.parallel `scala.collection.parallel`]] collections provide automatic parallel operation.
 
 Other important packages include:
 
-  - scala.[[scala.actors]] - Concurrency framework inspired by Erlang.
-  - scala.[[scala.io]] - Input and output.
-  - scala.[[scala.math]] - Basic math functions and additional numeric types.
-  - scala.[[scala.sys]] - Interaction with other processes and the operating system.
-  - scala.util.[[scala.util.matching]] - Pattern matching in text using regular expressions.
-  - scala.util.parsing.[[scala.util.parsing.combinator]] - Composable combinators for parsing.
-  - scala.[[scala.xml]] - XML parsing, manipulation, and serialization.
+  - [[scala.actors `scala.actors`]] - Concurrency framework inspired by Erlang.
+  - [[scala.io     `scala.io`]]     - Input and output.
+  - [[scala.math   `scala.math`]]   - Basic math functions and additional numeric types.
+  - [[scala.sys    `scala.sys`]]    - Interaction with other processes and the operating system.
+  - [[scala.util.matching `scala.util.matching`]] - Pattern matching in text using regular expressions.
+  - [[scala.util.parsing.combinator `scala.util.parsing.combinator`]] - Composable combinators for parsing.
+  - [[scala.xml    `scala.xml`]]    - XML parsing, manipulation, and serialization.
 
 Many other packages exist.  See the complete list on the left.
 
 == Automatic imports ==
 
-Identifiers in the scala package and the [[scala.Predef]] object are always in scope by default.
+Identifiers in the scala package and the [[scala.Predef `scala.Predef`]] object are always in scope by default.
 
-Some of these identifiers are type aliases provided as shortcuts to commonly used classes.  For example, `List` is an alias for scala.collection.immutable.[[scala.collection.immutable.List]].
+Some of these identifiers are type aliases provided as shortcuts to commonly used classes.  For example, `List` is an alias for
+[[scala.collection.immutable.List `scala.collection.immutable.List`]].
 
 Other aliases refer to classes provided by the underlying platform.  For example, on the JVM, `String` is an alias for `java.lang.String`.
diff --git a/src/library/scala/StringContext.scala b/src/library/scala/StringContext.scala
index e381c09398..4078168bb3 100644
--- a/src/library/scala/StringContext.scala
+++ b/src/library/scala/StringContext.scala
@@ -8,7 +8,7 @@
 
 package scala
 
-/** This class provides the basic mechanism to do String Interpolation.  
+/** This class provides the basic mechanism to do String Interpolation.
  * String Interpolation allows users
  * to embed variable references directly in *processed* string literals.
  * Here's an example:
@@ -26,7 +26,7 @@ package scala
  * is rewritten to be:
  *
  * {{{
- *   new StringContext("Hello, ", "").s(name)
+ *   StringContext("Hello, ", "").s(name)
  * }}}
  *
  * By default, this class provides the `raw`, `s` and `f` methods as
@@ -36,7 +36,7 @@ package scala
  * which adds a method to `StringContext`.  Here's an example:
  * {{{
  *    implicit class JsonHelper(val sc: StringContext) extends AnyVal {
- *     def json(args: Any*): JSONObject = ...
+ *      def json(args: Any*): JSONObject = ...
  *    }
  *    val x: JSONObject = json"{ a: $a }"
  * }}}
@@ -72,7 +72,7 @@ case class StringContext(parts: String*) {
    *    println(s"Hello, $name")  // Hello, James
    *  }}}
    *  In this example, the expression $name is replaced with the `toString` of the
-   *  variable `name`.  
+   *  variable `name`.
    *  The `s` interpolator can take the `toString` of any arbitrary expression within
    *  a `${}` block, for example:
    *  {{{
@@ -97,6 +97,13 @@ case class StringContext(parts: String*) {
    *
    *  For example, the raw processed string `raw"a\nb"` is equal to the scala string `"a\\nb"`.
    *
+   *  ''Note:'' Even when using the raw interpolator, Scala will preprocess unicode escapes.
+   *  For example:
+   *  {{{
+   *    scala> raw"\u0123"
+   *    res0: String = ģ
+   *  }}}
+   *
    *  @param `args` The arguments to be inserted into the resulting string.
    *  @throws An `IllegalArgumentException`
    *          if the number of `parts` in the enclosing `StringContext` does not exceed
diff --git a/src/library/scala/annotation/migration.scala b/src/library/scala/annotation/migration.scala
index f60c827620..a55c7006a1 100644
--- a/src/library/scala/annotation/migration.scala
+++ b/src/library/scala/annotation/migration.scala
@@ -25,6 +25,6 @@ package scala.annotation
  * @since 2.8
  */
  private[scala] final class migration(message: String, changedIn: String) extends scala.annotation.StaticAnnotation {
-   @deprecated("Use the constructor taking two Strings instead.", "2.10")
+   @deprecated("Use the constructor taking two Strings instead.", "2.10.0")
    def this(majorVersion: Int, minorVersion: Int, message: String) = this(message, majorVersion + "." + minorVersion)
  }
diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala
index d77d278fca..f912304680 100644
--- a/src/library/scala/collection/TraversableOnce.scala
+++ b/src/library/scala/collection/TraversableOnce.scala
@@ -366,9 +366,9 @@ trait TraversableOnce[+A] extends Any with GenTraversableOnce[A] {
 
 
 object TraversableOnce {
-  @deprecated("use OnceCanBuildFrom instead")
+  @deprecated("use OnceCanBuildFrom instead", "2.10.0")
   def traversableOnceCanBuildFrom[T] = new OnceCanBuildFrom[T]
-  @deprecated("use MonadOps instead")
+  @deprecated("use MonadOps instead", "2.10.0")
   def wrapTraversableOnce[A](trav: TraversableOnce[A]) = new MonadOps(trav)
 
   implicit def alternateImplicit[A](trav: TraversableOnce[A]) = new ForceImplicitAmbiguity
diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala
index 1b676e2d2f..d79e2adbda 100644
--- a/src/library/scala/collection/immutable/BitSet.scala
+++ b/src/library/scala/collection/immutable/BitSet.scala
@@ -31,7 +31,7 @@ abstract class BitSet extends scala.collection.AbstractSet[Int]
                          with Serializable {
   override def empty = BitSet.empty
 
-  @deprecated("Use BitSet.fromBitMask[NoCopy] instead of fromArray", "2.10")
+  @deprecated("Use BitSet.fromBitMask[NoCopy] instead of fromArray", "2.10.0")
   def fromArray(elems: Array[Long]): BitSet = fromBitMaskNoCopy(elems)
 
   protected def fromBitMaskNoCopy(elems: Array[Long]): BitSet = BitSet.fromBitMaskNoCopy(elems)
@@ -82,7 +82,7 @@ object BitSet extends BitSetFactory[BitSet] {
   implicit def canBuildFrom: CanBuildFrom[BitSet, Int, BitSet] = bitsetCanBuildFrom
 
   /** A bitset containing all the bits in an array */
-  @deprecated("Use fromBitMask[NoCopy] instead of fromArray", "2.10")
+  @deprecated("Use fromBitMask[NoCopy] instead of fromArray", "2.10.0")
   def fromArray(elems: Array[Long]): BitSet = fromBitMaskNoCopy(elems)
 
   /** A bitset containing all the bits in an array */
diff --git a/src/library/scala/collection/immutable/RedBlack.scala b/src/library/scala/collection/immutable/RedBlack.scala
index a3ab27f814..77e5a87e73 100644
--- a/src/library/scala/collection/immutable/RedBlack.scala
+++ b/src/library/scala/collection/immutable/RedBlack.scala
@@ -18,7 +18,7 @@ package immutable
  *
  *  @since 2.3
  */
-@deprecated("use `TreeMap` or `TreeSet` instead", "2.10")
+@deprecated("use `TreeMap` or `TreeSet` instead", "2.10.0")
 @SerialVersionUID(8691885935445612921L)
 abstract class RedBlack[A] extends Serializable {
 
diff --git a/src/library/scala/collection/immutable/TreeMap.scala b/src/library/scala/collection/immutable/TreeMap.scala
index 51bc76efc3..f7a24f3d66 100644
--- a/src/library/scala/collection/immutable/TreeMap.scala
+++ b/src/library/scala/collection/immutable/TreeMap.scala
@@ -51,7 +51,7 @@ class TreeMap[A, +B] private (tree: RB.Tree[A, B])(implicit val ordering: Orderi
      with MapLike[A, B, TreeMap[A, B]]
      with Serializable {
 
-  @deprecated("use `ordering.lt` instead", "2.10")
+  @deprecated("use `ordering.lt` instead", "2.10.0")
   def isSmaller(x: A, y: A) = ordering.lt(x, y)
 
   override protected[this] def newBuilder : Builder[(A, B), TreeMap[A, B]] =
diff --git a/src/library/scala/collection/immutable/TreeSet.scala b/src/library/scala/collection/immutable/TreeSet.scala
index 697da2bc4b..0fdb16c23b 100644
--- a/src/library/scala/collection/immutable/TreeSet.scala
+++ b/src/library/scala/collection/immutable/TreeSet.scala
@@ -96,7 +96,7 @@ class TreeSet[A] private (tree: RB.Tree[A, Unit])(implicit val ordering: Orderin
   override def takeWhile(p: A => Boolean) = take(countWhile(p))
   override def span(p: A => Boolean) = splitAt(countWhile(p))
 
-  @deprecated("use `ordering.lt` instead", "2.10")
+  @deprecated("use `ordering.lt` instead", "2.10.0")
   def isSmaller(x: A, y: A) = compare(x,y) < 0
 
   def this()(implicit ordering: Ordering[A]) = this(null)(ordering)
diff --git a/src/library/scala/language.scala b/src/library/scala/language.scala
index 297f344f65..c638f531bb 100644
--- a/src/library/scala/language.scala
+++ b/src/library/scala/language.scala
@@ -1,5 +1,28 @@
 package scala
 
+/**
+ *  The `scala.language` object controls the language features available to the programmer, as proposed in the
+ *  [[https://docs.google.com/document/d/1nlkvpoIRkx7at1qJEZafJwthZ3GeIklTFhqmXMvTX9Q/edit '''SIP-18 document''']].
+ *
+ *  Each of these features has to be explicitly imported into the current scope to become available:
+ *  {{{
+ *     import language.postfixOps // or language._
+ *     List(1, 2, 3) reverse
+ *  }}}
+ *
+ *  The language features are:
+ *   - [[dynamics            `dynamics`]]            enables defining calls rewriting using the [[scala.Dynamic `Dynamic`]] trait
+ *   - [[postfixOps          `postfixOps`]]          enables postfix operators
+ *   - [[reflectiveCalls     `reflectiveCalls`]]     enables using structural types
+ *   - [[implicitConversions `implicitConversions`]] enables defining implicit methods and members
+ *   - [[higherKinds         `higherKinds`]]         enables writing higher-kinded types
+ *   - [[existentials        `existentials`]]        enables writing existential types
+ *   - [[experimental        `experimental`]]        contains newer features that have not yet been tested in production
+ *
+ *  @groupname production   Language Features
+ *  @groupname experimental Experimental Language Features
+ *  @groupprio experimental 10
+ */
 object language {
 
   import languageFeature._
@@ -10,21 +33,25 @@ object language {
    *  selection of existing subclasses of trait Dynamic are unaffected;
    *  they can be used anywhere.
    *
-   *  _Why introduce the feature?_ To enable flexible DSLs and convenient interfacing
+   *  '''Why introduce the feature?''' To enable flexible DSLs and convenient interfacing
    *  with dynamic languages.
    *
-   *  _Why control it?_ Dynamic member selection can undermine static checkability
+   *  '''Why control it?''' Dynamic member selection can undermine static checkability
    *  of programs. Furthermore, dynamic member selection often relies on reflection,
    *  which is not available on all platforms.
+   *
+   *  @group production
    */
   implicit lazy val dynamics: dynamics = languageFeature.dynamics
 
   /** Only where enabled, postfix operator notation `(expr op)` will be allowed.
    *
-   *  _Why keep the feature?_ Several DSLs written in Scala need the notation.
+   *  '''Why keep the feature?''' Several DSLs written in Scala need the notation.
    *
-   *  _Why control it?_ Postfix operators interact poorly with semicolon inference.
+   *  '''Why control it?''' Postfix operators interact poorly with semicolon inference.
    *   Most programmers avoid them for this reason.
+   *
+   *  @group production
    */
   implicit lazy val postfixOps: postfixOps = languageFeature.postfixOps
 
@@ -34,13 +61,15 @@ object language {
    *  not override any member in `Parents`. To access one of these members, a
    *  reflective call is needed.
    *
-   *  _Why keep the feature?_ Structural types provide great flexibility because
+   *  '''Why keep the feature?''' Structural types provide great flexibility because
    *  they avoid the need to define inheritance hierarchies a priori. Besides,
    *  their definition falls out quite naturally from Scala’s concept of type refinement.
    *
-   *  _Why control it?+ Reflection is not available on all platforms. Popular tools
+   *  '''Why control it?''' Reflection is not available on all platforms. Popular tools
    *  such as ProGuard have problems dealing with it. Even where reflection is available,
    *  reflective dispatch can lead to surprising performance degradations.
+   *
+   *  @group production
    */
   implicit lazy val reflectiveCalls: reflectiveCalls = languageFeature.reflectiveCalls
 
@@ -49,32 +78,36 @@ object language {
    *  or an implicit method that has in its first parameter section a single,
    *  non-implicit parameter. Examples:
    *
+   *  {{{
    *     implicit def stringToInt(s: String): Int = s.length
    *     implicit val conv = (s: String) => s.length
-   *     implicit def listToX(xs: List[T])(implicit f: T => X): X = …
+   *     implicit def listToX(xs: List[T])(implicit f: T => X): X = ...
+   *  }}}
    *
    *  implicit values of other types are not affected, and neither are implicit
    *  classes.
    *
-   *  _Why keep the feature?_ Implicit conversions are central to many aspects
+   *  '''Why keep the feature?''' Implicit conversions are central to many aspects
    *  of Scala’s core libraries.
    *
-   *  _Why control it?_ Implicit conversions are known to cause many pitfalls
+   *  '''Why control it?''' Implicit conversions are known to cause many pitfalls
    *  if over-used. And there is a tendency to over-use them because they look
    *  very powerful and their effects seem to be easy to understand. Also, in
    *  most situations using implicit parameters leads to a better design than
    *  implicit conversions.
+   *
+   *  @group production
    */
   implicit lazy val implicitConversions: implicitConversions = languageFeature.implicitConversions
 
   /** Only where this flag is enabled, higher-kinded types can be written.
    *
-   *  _Why keep the feature?_ Higher-kinded types enable the definition of very general
+   *  '''Why keep the feature?''' Higher-kinded types enable the definition of very general
    *  abstractions such as functor, monad, or arrow. A significant set of advanced
    *  libraries relies on them. Higher-kinded types are also at the core of the
    *  scala-virtualized effort to produce high-performance parallel DSLs through staging.
    *
-   *  _Why control it?_ Higher kinded types in Scala lead to a Turing-complete
+   *  '''Why control it?''' Higher kinded types in Scala lead to a Turing-complete
    *  type system, where compiler termination is no longer guaranteed. They tend
    *  to be useful mostly for type-level computation and for highly generic design
    *  patterns. The level of abstraction implied by these design patterns is often
@@ -85,6 +118,8 @@ object language {
    *  higher-kinded types will change in future versions of Scala. So an explicit
    *  enabling also serves as a warning that code involving higher-kinded types
    *  might have to be slightly revised in the future.
+   *
+   *  @group production
    */
   implicit lazy val higherKinds: higherKinds = languageFeature.higherKinds
 
@@ -93,17 +128,31 @@ object language {
    *  types of methods. Existential types with wildcard type syntax such as `List[_]`,
    *  or `Map[String, _]` are not affected.
    *
-   *  _Why keep the feature?_ Existential types are needed to make sense of Java’s wildcard
+   *  '''Why keep the feature?''' Existential types are needed to make sense of Java’s wildcard
    *  types and raw types and the erased types of run-time values.
    *
-   *  Why control it? Having complex existential types in a code base usually makes
+   *  '''Why control it?''' Having complex existential types in a code base usually makes
    *  application code very brittle, with a tendency to produce type errors with
    *  obscure error messages. Therefore, going overboard with existential types
    *  is generally perceived not to be a good idea. Also, complicated existential types
    *  might be no longer supported in a future simplification of the language.
+   *
+   *  @group production
    */
   implicit lazy val existentials: existentials = languageFeature.existentials
 
+  /** The experimental object contains features that have been recently added but have not
+   *  been thoroughly tested in production yet.
+   *
+   *  Experimental features '''may undergo API changes''' in future releases, so production
+   *  code should not rely on them.
+   *
+   *  Programmers are encouraged to try out experimental features and
+   *  [[http://issues.scala-lang.org report any bugs or API inconsistencies]]
+   *  they encounter so they can be improved in future releases.
+   *
+   *  @group experimental
+   */
   object experimental {
 
     import languageFeature.experimental._
@@ -111,12 +160,12 @@ object language {
     /** Where enabled, macro definitions are allowed. Macro implementations and
      *  macro applications are unaffected; they can be used anywhere.
      *
-     *  _Why introduce the feature?_ Macros promise to make the language more regular,
+     *  '''Why introduce the feature?''' Macros promise to make the language more regular,
      *  replacing ad-hoc language constructs with a general powerful abstraction
      *  capability that can express them. Macros are also a more disciplined and
      *  powerful replacement for compiler plugins.
      *
-     *  _Why control it?_ For their very power, macros can lead to code that is hard
+     *  '''Why control it?''' For their very power, macros can lead to code that is hard
      *  to debug and understand.
      */
     implicit lazy val macros: macros = languageFeature.experimental.macros
diff --git a/src/library/scala/testing/Show.scala b/src/library/scala/testing/Show.scala
index da1868c7f6..c6c58f5da2 100644
--- a/src/library/scala/testing/Show.scala
+++ b/src/library/scala/testing/Show.scala
@@ -37,7 +37,7 @@ trait Show {
     }
   }
 
-  @deprecated("use SymApply instead", "2.10")
+  @deprecated("use SymApply instead", "2.10.0")
   def symApply(sym: Symbol): SymApply = new SymApply(sym)
 
   /** Apply method with name of given symbol `f` to given arguments and return
diff --git a/src/library/scala/throws.scala b/src/library/scala/throws.scala
index 0aa0d31c9f..02dffb00b0 100644
--- a/src/library/scala/throws.scala
+++ b/src/library/scala/throws.scala
@@ -14,7 +14,7 @@ package scala
  * {{{
  * class Reader(fname: String) {
  *   private val in = new BufferedReader(new FileReader(fname))
- *   @throws(classOf[IOException])
+ *   @throws[IOException]("if the file doesn't exist")
  *   def read() = in.read()
  * }
  * }}}
@@ -23,4 +23,6 @@ package scala
  * @version 1.0, 19/05/2006
  * @since   2.1
  */
-class throws(clazz: Class[_]) extends scala.annotation.StaticAnnotation
+class throws[T <: Throwable](cause: String = "") extends scala.annotation.StaticAnnotation {
+  def this(clazz: Class[T]) = this()
+}
diff --git a/src/library/scala/util/Either.scala b/src/library/scala/util/Either.scala
index f0253eee07..51342eda78 100644
--- a/src/library/scala/util/Either.scala
+++ b/src/library/scala/util/Either.scala
@@ -221,7 +221,7 @@ object Either {
       case Right(a) => a
     }
   }
-  @deprecated("use MergeableEither instead", "2.10")
+  @deprecated("use MergeableEither instead", "2.10.0")
   def either2mergeable[A](x: Either[A, A]): MergeableEither[A] = new MergeableEither(x)
 
   /**
diff --git a/src/library/scala/xml/Elem.scala b/src/library/scala/xml/Elem.scala
index 2ca1dbfcd0..a92d7859c3 100755
--- a/src/library/scala/xml/Elem.scala
+++ b/src/library/scala/xml/Elem.scala
@@ -59,7 +59,7 @@ class Elem(
   val child: Node*)
 extends Node with Serializable
 {
-  @deprecated("This constructor is retained for backward compatibility. Please use the primary constructor, which lets you specify your own preference for `minimizeEmpty`.", "2.10")
+  @deprecated("This constructor is retained for backward compatibility. Please use the primary constructor, which lets you specify your own preference for `minimizeEmpty`.", "2.10.0")
   def this(prefix: String, label: String, attributes: MetaData, scope: NamespaceBinding, child: Node*) = {
     this(prefix, label, attributes, scope, child.isEmpty, child: _*)
   }
diff --git a/src/library/scala/xml/Utility.scala b/src/library/scala/xml/Utility.scala
index 50a284d7cd..b390235d59 100755
--- a/src/library/scala/xml/Utility.scala
+++ b/src/library/scala/xml/Utility.scala
@@ -175,7 +175,7 @@ object Utility extends AnyRef with parsing.TokenTests {
    * Note that calling this source-compatible method will result in the same old, arguably almost universally unwanted,
    * behaviour.
    */
-  @deprecated("Please use `serialize` instead and specify a `minimizeTags` parameter", "2.10")
+  @deprecated("Please use `serialize` instead and specify a `minimizeTags` parameter", "2.10.0")
   def toXML(
     x: Node,
     pscope: NamespaceBinding = TopScope,