Merge remote-tracking branch 'origin/2.10.x' into merge-210

* origin/2.10.x: (52 commits)
  JavaUniverse
  Moved @contentDiagram in Symbols
  Adds lots of new documentation for TypeTags, Mirrors, Universes and more
  runtime.JavaUniverse - put ungrouped members at the top
  Forgotten annotation in Annotations
  Diagram tweaking
  Grouping for reflection and macros
  fixes a typo
  scala.reflect.api.Symbols documentation
  Symbols docs cleanup, mostly moved to guide
  scala.reflect.api.Position documentation
  scala.reflect.api.StandardNames documentation
  scala.reflect.api.Constants documentation
  removed docs for internal TypeCreator and TreeCreator
  simplified reflection docs for trees
  Rearranged some reflection docs, moving things to the guide
  reflection docs improvements and moves to doc page
  docs for reflection and macros
  SI-6509 Correct @template owners
  SI-6155 Scaladoc @template diagrms
  ...

Conflicts:
	src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
	src/compiler/scala/tools/nsc/typechecker/Typers.scala
	src/reflect/scala/reflect/api/Trees.scala
	test/scaladoc/run/links.scala

7 files changed, 100 insertions, 74 deletions

diff --git a/src/library/scala/annotation/switch.scala b/src/library/scala/annotation/switch.scala
index a867783455..20056bc03c 100644
--- a/src/library/scala/annotation/switch.scala
+++ b/src/library/scala/annotation/switch.scala
@@ -9,8 +9,7 @@ package scala.annotation
 
 /** An annotation to be applied to a match expression.  If present,
  *  the compiler will verify that the match has been compiled to a
- *  [[http://docs.oracle.com/javase/specs/jvms/se5.0/html/Instructions2.doc14.html tableswitch]]
- *  or [[http://docs.oracle.com/javase/specs/jvms/se5.0/html/Instructions2.doc8.html#lookupswitch lookupswitch]]
+ *  [[http://docs.oracle.com/javase/specs/jvms/se7/html/jvms-3.html#jvms-3.10 tableswitch or lookupswitch]]
  *  and issue an error if it instead compiles into a series of conditional expressions.
  *  Example usage:
 {{{
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index ce0b130b86..7849f1c544 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -271,12 +271,7 @@ trait TraversableLike[+A, +Repr] extends Any
    *  @return      a new $coll consisting of all elements of this $coll that do not satisfy the given
    *               predicate `p`. The order of the elements is preserved.
    */
-  def filterNot(p: A => Boolean): Repr = {
-    val b = newBuilder
-    for (x <- this)
-      if (!p(x)) b += x
-    b.result
-  }
+  def filterNot(p: A => Boolean): Repr = filter(!p(_))
 
   def collect[B, That](pf: PartialFunction[A, B])(implicit bf: CanBuildFrom[Repr, B, That]): That = {
     val b = bf(repr)
diff --git a/src/library/scala/concurrent/Awaitable.scala b/src/library/scala/concurrent/Awaitable.scala
index 3bd7617bce..c0c688bf42 100644
--- a/src/library/scala/concurrent/Awaitable.scala
+++ b/src/library/scala/concurrent/Awaitable.scala
@@ -14,36 +14,47 @@ import scala.concurrent.duration.Duration
 
 
 
+/**
+ * An object that may eventually be completed with a result value of type `T` which may be
+ * awaited using blocking methods.
+ * 
+ * The [[Await]] object provides methods that allow accessing the result of an `Awaitable`
+ * by blocking the current thread until the `Awaitable` has been completed or a timeout has
+ * occurred.
+ */
 trait Awaitable[+T] {
+
   /**
-   * Await the "resolved" state of this Awaitable.
-   * This method should not be called directly.
-   *
-   * @param atMost
-   *        maximum wait time, which may be negative (no waiting is done),
-   *        [[Duration.Inf]] for unbounded waiting, or a finite positive
-   *        duration
-   * @return the Awaitable itself
-   * @throws InterruptedException     if the wait call was interrupted
-   * @throws TimeoutException         if after waiting for the specified time this Awaitable is still not ready
-   * @throws IllegalArgumentException if `atMost` is [[Duration.Undefined]]
+   * Await the "completed" state of this `Awaitable`.
+   * 
+   * '''''This method should not be called directly; use [[Await.ready]] instead.'''''
+   * 
+   * @param  atMost
+   *         maximum wait time, which may be negative (no waiting is done),
+   *         [[scala.concurrent.duration.Duration.Inf Duration.Inf]] for unbounded waiting, or a finite positive
+   *         duration
+   * @return this `Awaitable`
+   * @throws InterruptedException     if the current thread is interrupted while waiting
+   * @throws TimeoutException         if after waiting for the specified time this `Awaitable` is still not ready
+   * @throws IllegalArgumentException if `atMost` is [[scala.concurrent.duration.Duration.Undefined Duration.Undefined]]
    */
   @throws(classOf[TimeoutException])
   @throws(classOf[InterruptedException])
   def ready(atMost: Duration)(implicit permit: CanAwait): this.type
   
   /**
-   * Await and return the result of this Awaitable, which is either of type T or a thrown exception (any Throwable).
-   * This method should not be called directly.
-   *
-   * @param atMost
-   *        maximum wait time, which may be negative (no waiting is done),
-   *        [[Duration.Inf]] for unbounded waiting, or a finite positive
-   *        duration
-   * @return the value if the Awaitable was successful within the specific maximum wait time
-   * @throws InterruptedException     if the wait call was interrupted
-   * @throws TimeoutException         if after waiting for the specified time this Awaitable is still not ready
-   * @throws IllegalArgumentException if `atMost` is [[Duration.Undefined]]
+   * Await and return the result (of type `T`) of this `Awaitable`.
+   * 
+   * '''''This method should not be called directly; use [[Await.result]] instead.'''''
+   * 
+   * @param  atMost
+   *         maximum wait time, which may be negative (no waiting is done),
+   *         [[scala.concurrent.duration.Duration.Inf Duration.Inf]] for unbounded waiting, or a finite positive
+   *         duration
+   * @return the result value if the `Awaitable` is completed within the specific maximum wait time
+   * @throws InterruptedException     if the current thread is interrupted while waiting
+   * @throws TimeoutException         if after waiting for the specified time this `Awaitable` is still not ready
+   * @throws IllegalArgumentException if `atMost` is [[scala.concurrent.duration.Duration.Undefined Duration.Undefined]]
    */
   @throws(classOf[Exception])
   def result(atMost: Duration)(implicit permit: CanAwait): T
diff --git a/src/library/scala/concurrent/package.scala b/src/library/scala/concurrent/package.scala
index e683732e41..c0d46df883 100644
--- a/src/library/scala/concurrent/package.scala
+++ b/src/library/scala/concurrent/package.scala
@@ -23,7 +23,7 @@ package object concurrent {
    *  The result becomes available once the asynchronous computation is completed.
    *  
    *  @tparam T       the type of the result
-   *  @param body     the asychronous computation
+   *  @param body     the asynchronous computation
    *  @param execctx  the execution context on which the future is run
    *  @return         the `Future` holding the result of the computation
    */
@@ -37,17 +37,15 @@ package object concurrent {
    */
   def promise[T]()(implicit execctx: ExecutionContext): Promise[T] = Promise[T]()
 
-  /** Used to designate a piece of code which potentially blocks, allowing the BlockContext to adjust the runtime's behavior.
+  /** Used to designate a piece of code which potentially blocks, allowing the current [[BlockContext]] to adjust
+   *  the runtime's behavior.
    *  Properly marking blocking code may improve performance or avoid deadlocks. 
    *
-   *  If you have an `Awaitable` then you should use Await.result instead of `blocking`.
+   *  Blocking on an [[Awaitable]] should be done using [[Await.result]] instead of `blocking`.
    *
    *  @param body         A piece of code which contains potentially blocking or long running calls.
-   *
-   *  Calling this method may throw the following exceptions:
-   *  - CancellationException - if the computation was cancelled
-   *  - InterruptedException - in the case that a wait within the blockable object was interrupted
-   *  - TimeoutException - in the case that the blockable object timed out
+   *  @throws `CancellationException` if the computation was cancelled
+   *  @throws `InterruptedException` in the case that a wait within the blocking `body` was interrupted
    */
   @throws(classOf[Exception])
   def blocking[T](body: =>T): T = BlockContext.current.blockOn(body)(scala.concurrent.AwaitPermission)
@@ -67,19 +65,21 @@ package concurrent {
    */
   object Await {
     /**
-     * Await the "resolved" state of this Awaitable.
-     * Invokes ready() on the awaitable, properly wrapped by a call to `scala.concurrent.blocking`.
-     *
-     * @param awaitable
-     *        the `Awaitable` on which `ready` is to be called
-     * @param atMost
-     *        maximum wait time, which may be negative (no waiting is done),
-     *        [[Duration.Inf]] for unbounded waiting, or a finite positive
-     *        duration
-     * @return the awaitable itself
-     * @throws InterruptedException     if the wait call was interrupted
-     * @throws TimeoutException         if after waiting for the specified time this Awaitable is still not ready
-     * @throws IllegalArgumentException if `atMost` is [[Duration.Undefined]]
+     * Await the "completed" state of an `Awaitable`.
+     * 
+     * Although this method is blocking, the internal use of [[scala.concurrent.blocking blocking]] ensures that
+     * the underlying [[ExecutionContext]] is prepared to properly manage the blocking.
+     * 
+     * @param  awaitable
+     *         the `Awaitable` to be awaited
+     * @param  atMost
+     *         maximum wait time, which may be negative (no waiting is done),
+     *         [[scala.concurrent.duration.Duration.Inf Duration.Inf]] for unbounded waiting, or a finite positive
+     *         duration
+     * @return the `awaitable`
+     * @throws InterruptedException     if the current thread is interrupted while waiting
+     * @throws TimeoutException         if after waiting for the specified time this `Awaitable` is still not ready
+     * @throws IllegalArgumentException if `atMost` is [[scala.concurrent.duration.Duration.Undefined Duration.Undefined]]
      */
     @throws(classOf[TimeoutException])
     @throws(classOf[InterruptedException])
@@ -87,19 +87,21 @@ package concurrent {
       blocking(awaitable.ready(atMost)(AwaitPermission))
     
     /**
-     * Await and return the result of this Awaitable, which is either of type T or a thrown exception (any Throwable).
-     * Invokes result() on the awaitable, properly wrapped by a call to `scala.concurrent.blocking`.
-     *
-     * @param awaitable
-     *        the `Awaitable` on which `result` is to be called
-     * @param atMost
-     *        maximum wait time, which may be negative (no waiting is done),
-     *        [[Duration.Inf]] for unbounded waiting, or a finite positive
-     *        duration
-     * @return the value if the Awaitable was successful within the specific maximum wait time
-     * @throws InterruptedException     if the wait call was interrupted
-     * @throws TimeoutException         if after waiting for the specified time this Awaitable is still not ready
-     * @throws IllegalArgumentException if `atMost` is [[Duration.Undefined]]
+     * Await and return the result (of type `T`) of an `Awaitable`.
+     * 
+     * Although this method is blocking, the internal use of [[scala.concurrent.blocking blocking]] ensures that
+     * the underlying [[ExecutionContext]] to properly detect blocking and ensure that there are no deadlocks.
+     * 
+     * @param  awaitable
+     *         the `Awaitable` to be awaited
+     * @param  atMost
+     *         maximum wait time, which may be negative (no waiting is done),
+     *         [[scala.concurrent.duration.Duration.Inf Duration.Inf]] for unbounded waiting, or a finite positive
+     *         duration
+     * @return the result value if `awaitable` is completed within the specific maximum wait time
+     * @throws InterruptedException     if the current thread is interrupted while waiting
+     * @throws TimeoutException         if after waiting for the specified time `awaitable` is still not ready
+     * @throws IllegalArgumentException if `atMost` is [[scala.concurrent.duration.Duration.Undefined Duration.Undefined]]
      */
     @throws(classOf[Exception])
     def result[T](awaitable: Awaitable[T], atMost: Duration): T =
diff --git a/src/library/scala/package.scala b/src/library/scala/package.scala
index a41cdedfa9..fbb98d0582 100644
--- a/src/library/scala/package.scala
+++ b/src/library/scala/package.scala
@@ -95,7 +95,10 @@ package object scala {
   val Equiv = scala.math.Equiv
 
   type Fractional[T] = scala.math.Fractional[T]
+  val Fractional = scala.math.Fractional
+
   type Integral[T] = scala.math.Integral[T]
+  val Integral = scala.math.Integral
 
   type Numeric[T] = scala.math.Numeric[T]
   val Numeric = scala.math.Numeric
diff --git a/src/library/scala/reflect/ClassTag.scala b/src/library/scala/reflect/ClassTag.scala
index 5c2067a548..d699e34ffc 100644
--- a/src/library/scala/reflect/ClassTag.scala
+++ b/src/library/scala/reflect/ClassTag.scala
@@ -5,19 +5,34 @@ import java.lang.{ Class => jClass }
 import scala.language.{implicitConversions, existentials}
 import scala.runtime.ScalaRunTime.{ arrayClass, arrayElementClass }
 
-/** A `ClassTag[T]` wraps a runtime class (the erasure) and can create array instances.
+/**
+ *
+ * A `ClassTag[T]` stores the erased class of a given type `T`, accessible via the `runtimeClass`
+ * field. This is particularly useful for instantiating `Array`s whose element types are unknown
+ * at compile time.
+ *
+ * `ClassTag`s are a weaker special case of [[scala.reflect.api.TypeTags#TypeTag]]s, in that they
+ * wrap only the runtime class of a given type, whereas a `TypeTag` contains all static type
+ * information. That is, `ClassTag`s are constructed from knowing only the top-level class of a
+ * type, without necessarily knowing all of its argument types. This runtime information is enough
+ * for runtime `Array` creation.
  *
- *  If an implicit value of type ClassTag[T] is requested, the compiler will create one.
- *  The runtime class (i.e. the erasure, a java.lang.Class on the JVM) of T can be accessed
- *  via the `runtimeClass` field. References to type parameters or abstract type members are
- *  replaced by the concrete types if ClassTags are available for them.
+ * For example:
+ * {{{
+ *   scala> def mkArray[T : ClassTag](elems: T*) = Array[T](elems: _*)
+ *   mkArray: [T](elems: T*)(implicit evidence$1: scala.reflect.ClassTag[T])Array[T]
  *
- *  Besides accessing the erasure, a ClassTag knows how to instantiate single- and multi-
- *  dimensional `Arrays` where the element type is unknown at compile time.
+ *   scala> mkArray(42, 13)
+ *   res0: Array[Int] = Array(42, 13)
  *
- * [[scala.reflect.ClassTag]] corresponds to a previous concept of [[scala.reflect.ClassManifest]].
+ *   scala> mkArray("Japan","Brazil","Germany")
+ *   res1: Array[String] = Array(Japan, Brazil, Germany)
+ * }}}
+ * 
+ * See [[scala.reflect.api.TypeTags]] for more examples, or the
+ * [[http://docs.scala-lang.org/overviews/reflection/typetags-manifests.html Reflection Guide: TypeTags]]
+ * for more details.
  *
- * @see [[scala.reflect.api.TypeTags]]
  */
 @scala.annotation.implicitNotFound(msg = "No ClassTag available for ${T}")
 trait ClassTag[T] extends ClassManifestDeprecatedApis[T] with Equals with Serializable {
@@ -29,7 +44,7 @@ trait ClassTag[T] extends ClassManifestDeprecatedApis[T] with Equals with Serial
    */
   def runtimeClass: jClass[_]
 
-  /** Produces a `ClassTag` that knows how to build `Array[Array[T]]` */
+  /** Produces a `ClassTag` that knows how to instantiate an `Array[Array[T]]` */
   def wrap: ClassTag[Array[T]] = ClassTag[Array[T]](arrayClass(runtimeClass))
 
   /** Produces a new array with element type `T` and length `len` */
diff --git a/src/library/scala/runtime/WorksheetSupport.scala b/src/library/scala/runtime/WorksheetSupport.scala
index a003bba034..016a0d04e0 100644
--- a/src/library/scala/runtime/WorksheetSupport.scala
+++ b/src/library/scala/runtime/WorksheetSupport.scala
@@ -4,6 +4,7 @@ import scala.runtime.ScalaRunTime.stringOf
 
 /** A utility object that's needed by the code that executes a worksheet.
  */
+@deprecated("SI-6458: Instrumentation logic will be moved out of the compiler.","2.10.0")
 object WorksheetSupport {
 
   /** The offset in the source which should be printed */