Merge remote-tracking branch 'origin/2.10.0-wip' into merge-210-wip-210

# By Eugene Burmako (23) and others
# Via Josh Suereth (12) and others
* origin/2.10.0-wip: (54 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
  ...

11 files changed, 119 insertions, 85 deletions

diff --git a/src/library/scala/Predef.scala b/src/library/scala/Predef.scala
index 4792de6bf5..f0854dd6e2 100644
--- a/src/library/scala/Predef.scala
+++ b/src/library/scala/Predef.scala
@@ -103,23 +103,29 @@ object Predef extends LowPriorityImplicits {
   @annotation.implicitNotFound(msg = "No ClassManifest available for ${T}.")
   @deprecated("Use scala.reflect.ClassTag instead", "2.10.0")
   type ClassManifest[T] = scala.reflect.ClassManifest[T]
-  @deprecated("This notion doesn't have a corresponding concept in 2.10, because scala.reflect.runtime.universe.TypeTag can capture arbitrary types. Use type tags instead of manifests, and there will be no need in opt manifests.", "2.10.0")
+  // TODO undeprecated until Scala reflection becomes non-experimental
+  // @deprecated("This notion doesn't have a corresponding concept in 2.10, because scala.reflect.runtime.universe.TypeTag can capture arbitrary types. Use type tags instead of manifests, and there will be no need in opt manifests.", "2.10.0")
   type OptManifest[T]   = scala.reflect.OptManifest[T]
   @annotation.implicitNotFound(msg = "No Manifest available for ${T}.")
-  @deprecated("Use scala.reflect.ClassTag (to capture erasures) or scala.reflect.runtime.universe.TypeTag (to capture types) or both instead", "2.10.0")
+  // TODO undeprecated until Scala reflection becomes non-experimental
+  // @deprecated("Use scala.reflect.ClassTag (to capture erasures) or scala.reflect.runtime.universe.TypeTag (to capture types) or both instead", "2.10.0")
   type Manifest[T]      = scala.reflect.Manifest[T]
   @deprecated("Use scala.reflect.ClassTag instead", "2.10.0")
   val ClassManifest     = scala.reflect.ClassManifest
-  @deprecated("Use scala.reflect.ClassTag (to capture erasures) or scala.reflect.runtime.universe.TypeTag (to capture types) or both instead", "2.10.0")
+  // TODO undeprecated until Scala reflection becomes non-experimental
+  // @deprecated("Use scala.reflect.ClassTag (to capture erasures) or scala.reflect.runtime.universe.TypeTag (to capture types) or both instead", "2.10.0")
   val Manifest          = scala.reflect.Manifest
-  @deprecated("This notion doesn't have a corresponding concept in 2.10, because scala.reflect.runtime.universe.TypeTag can capture arbitrary types. Use type tags instead of manifests, and there will be no need in opt manifests.", "2.10.0")
+  // TODO undeprecated until Scala reflection becomes non-experimental
+  // @deprecated("This notion doesn't have a corresponding concept in 2.10, because scala.reflect.runtime.universe.TypeTag can capture arbitrary types. Use type tags instead of manifests, and there will be no need in opt manifests.", "2.10.0")
   val NoManifest        = scala.reflect.NoManifest
 
-  @deprecated("Use scala.reflect.classTag[T] and scala.reflect.runtime.universe.typeTag[T] instead", "2.10.0")
+  // TODO undeprecated until Scala reflection becomes non-experimental
+  // @deprecated("Use scala.reflect.classTag[T] and scala.reflect.runtime.universe.typeTag[T] instead", "2.10.0")
   def manifest[T](implicit m: Manifest[T])           = m
   @deprecated("Use scala.reflect.classTag[T] instead", "2.10.0")
   def classManifest[T](implicit m: ClassManifest[T]) = m
-  @deprecated("This notion doesn't have a corresponding concept in 2.10, because scala.reflect.runtime.universe.TypeTag can capture arbitrary types. Use type tags instead of manifests, and there will be no need in opt manifests.", "2.10.0")
+  // TODO undeprecated until Scala reflection becomes non-experimental
+  // @deprecated("This notion doesn't have a corresponding concept in 2.10, because scala.reflect.runtime.universe.TypeTag can capture arbitrary types. Use type tags instead of manifests, and there will be no need in opt manifests.", "2.10.0")
   def optManifest[T](implicit m: OptManifest[T])     = m
 
   // Minor variations on identity functions
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/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/reflect/Manifest.scala b/src/library/scala/reflect/Manifest.scala
index 8b021e0444..e3e1dfdbf7 100644
--- a/src/library/scala/reflect/Manifest.scala
+++ b/src/library/scala/reflect/Manifest.scala
@@ -39,7 +39,8 @@ import scala.collection.mutable.{ ArrayBuilder, WrappedArray }
  *
  */
 @scala.annotation.implicitNotFound(msg = "No Manifest available for ${T}.")
-@deprecated("Use scala.reflect.ClassTag (to capture erasures) or scala.reflect.runtime.universe.TypeTag (to capture types) or both instead", "2.10.0")
+// TODO undeprecated until Scala reflection becomes non-experimental
+// @deprecated("Use scala.reflect.ClassTag (to capture erasures) or scala.reflect.runtime.universe.TypeTag (to capture types) or both instead", "2.10.0")
 trait Manifest[T] extends ClassManifest[T] with Equals {
   override def typeArguments: List[Manifest[_]] = Nil
 
@@ -60,7 +61,8 @@ trait Manifest[T] extends ClassManifest[T] with Equals {
   override def hashCode = this.erasure.##
 }
 
-@deprecated("Use type tags and manually check the corresponding class or type instead", "2.10.0")
+// TODO undeprecated until Scala reflection becomes non-experimental
+// @deprecated("Use type tags and manually check the corresponding class or type instead", "2.10.0")
 abstract class AnyValManifest[T <: AnyVal](override val toString: String) extends Manifest[T] with Equals {
   override def <:<(that: ClassManifest[_]): Boolean =
     (that eq this) || (that eq Manifest.Any) || (that eq Manifest.AnyVal)
diff --git a/src/library/scala/reflect/NoManifest.scala b/src/library/scala/reflect/NoManifest.scala
index 95b4ddca1c..4f9c954235 100644
--- a/src/library/scala/reflect/NoManifest.scala
+++ b/src/library/scala/reflect/NoManifest.scala
@@ -10,7 +10,8 @@ package scala.reflect
 
 /** One of the branches of an [[scala.reflect.OptManifest]].
   */
-@deprecated("This notion doesn't have a corresponding concept in 2.10, because scala.reflect.runtime.universe.TypeTag can capture arbitrary types. Use type tags instead of manifests, and there will be no need in opt manifests.", "2.10.0")
+// TODO undeprecated until Scala reflection becomes non-experimental
+// @deprecated("This notion doesn't have a corresponding concept in 2.10, because scala.reflect.runtime.universe.TypeTag can capture arbitrary types. Use type tags instead of manifests, and there will be no need in opt manifests.", "2.10.0")
 object NoManifest extends OptManifest[Nothing] with Serializable {
   override def toString = "<?>"
 }
\ No newline at end of file
diff --git a/src/library/scala/reflect/OptManifest.scala b/src/library/scala/reflect/OptManifest.scala
index 0ea66cb53d..e3fa84b4b6 100644
--- a/src/library/scala/reflect/OptManifest.scala
+++ b/src/library/scala/reflect/OptManifest.scala
@@ -14,5 +14,6 @@ package scala.reflect
  *
  *  @author Martin Odersky
  */
-@deprecated("This notion doesn't have a corresponding concept in 2.10, because scala.reflect.runtime.universe.TypeTag can capture arbitrary types. Use type tags instead of manifests, and there will be no need in opt manifests.", "2.10.0")
+// TODO undeprecated until Scala reflection becomes non-experimental
+// @deprecated("This notion doesn't have a corresponding concept in 2.10, because scala.reflect.runtime.universe.TypeTag can capture arbitrary types. Use type tags instead of manifests, and there will be no need in opt manifests.", "2.10.0")
 trait OptManifest[+T] extends Serializable
\ No newline at end of file
diff --git a/src/library/scala/reflect/package.scala b/src/library/scala/reflect/package.scala
index 4f1cc03dc8..10e6d7d9a4 100644
--- a/src/library/scala/reflect/package.scala
+++ b/src/library/scala/reflect/package.scala
@@ -36,7 +36,8 @@ package object reflect {
   /** The object `Manifest` defines factory methods for manifests.
    *  It is intended for use by the compiler and should not be used in client code.
    */
-  @deprecated("Use scala.reflect.ClassTag (to capture erasures), scala.reflect.runtime.universe.TypeTag (to capture types) or both instead", "2.10.0")
+  // TODO undeprecated until Scala reflection becomes non-experimental
+  // @deprecated("Use scala.reflect.ClassTag (to capture erasures), scala.reflect.runtime.universe.TypeTag (to capture types) or both instead", "2.10.0")
   val Manifest = ManifestFactory
 
   def classTag[T](implicit ctag: ClassTag[T]) = ctag
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 */