Merge branch '2.10.0-wip' into merge-2.10.0

90 files changed, 480 insertions, 333 deletions

diff --git a/src/reflect/scala/reflect/api/Annotations.scala b/src/reflect/scala/reflect/api/Annotations.scala
index fb353a5520..09eaf7afb4 100644
--- a/src/reflect/scala/reflect/api/Annotations.scala
+++ b/src/reflect/scala/reflect/api/Annotations.scala
@@ -3,7 +3,10 @@ package api
 
 import scala.collection.immutable.ListMap
 
-/** This trait provides annotation support for the reflection API.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ * This trait provides annotation support for the reflection API.
  *
  *  The API distinguishes between two kinds of annotations:
  *
@@ -13,9 +16,9 @@ import scala.collection.immutable.ListMap
  *  is automatically added as a subclass to every Java annotation.</li>
  *  <li>''Scala annotations'': annotations on definitions or types produced by the Scala compiler.</li>
  *  </ul>
- *    
- *  When a Scala annotation that inherits from [[scala.annotation.StaticAnnotation]] or [[scala.annotation.ClassfileAnnotation]] is compiled, 
- *  it is stored as special attributes in the corresponding classfile, and not as a Java annotation. Note that subclassing 
+ *
+ *  When a Scala annotation that inherits from [[scala.annotation.StaticAnnotation]] or [[scala.annotation.ClassfileAnnotation]] is compiled,
+ *  it is stored as special attributes in the corresponding classfile, and not as a Java annotation. Note that subclassing
  *  just [[scala.annotation.Annotation]] is not enough to have the corresponding metadata persisted for runtime reflection.
  *
  *  The distinction between Java and Scala annotations is manifested in the contract of [[scala.reflect.api.Annotations#Annotation]], which exposes
@@ -29,7 +32,10 @@ import scala.collection.immutable.ListMap
  *    - arrays and
  *    - nested annotations.
  *
+ *  For more information about `Annotation`s, see the [[http://docs.scala-lang.org/overviews/reflection/annotations-names-scopes.html Reflection Guide: Annotations, Names, Scopes, and More]]
+ *
  *  @contentDiagram hideNodes "*Api"
+ *  @group ReflectionAPI
  */
 trait Annotations { self: Universe =>
 
@@ -45,7 +51,7 @@ trait Annotations { self: Universe =>
    */
   implicit val AnnotationTag: ClassTag[Annotation]
 
-   /** The constructor/deconstructor for `Annotation` instances.
+   /** The constructor/extractor for `Annotation` instances.
     *  @group Extractors
     */
    val Annotation: AnnotationExtractor
@@ -102,7 +108,7 @@ trait Annotations { self: Universe =>
    */
   implicit val LiteralArgumentTag: ClassTag[LiteralArgument]
 
-  /** The constructor/deconstructor for `LiteralArgument` instances.
+  /** The constructor/extractor for `LiteralArgument` instances.
    *  @group Extractors
    */
   val LiteralArgument: LiteralArgumentExtractor
@@ -137,7 +143,7 @@ trait Annotations { self: Universe =>
    */
   implicit val ArrayArgumentTag: ClassTag[ArrayArgument]
 
-  /** The constructor/deconstructor for `ArrayArgument` instances.
+  /** The constructor/extractor for `ArrayArgument` instances.
    *  @group Extractors
    */
   val ArrayArgument: ArrayArgumentExtractor
@@ -172,7 +178,7 @@ trait Annotations { self: Universe =>
    */
   implicit val NestedArgumentTag: ClassTag[NestedArgument]
 
-  /** The constructor/deconstructor for `NestedArgument` instances.
+  /** The constructor/extractor for `NestedArgument` instances.
    *  @group Extractors
    */
   val NestedArgument: NestedArgumentExtractor
diff --git a/src/reflect/scala/reflect/api/Constants.scala b/src/reflect/scala/reflect/api/Constants.scala
index a92fc5cbb3..f3d75c3c00 100644
--- a/src/reflect/scala/reflect/api/Constants.scala
+++ b/src/reflect/scala/reflect/api/Constants.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
@@ -7,6 +7,8 @@ package scala.reflect
 package api
 
 /**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
  *  According to the section 6.24 "Constant Expressions" of the Scala language specification,
  *  certain expressions (dubbed ''constant expressions'') can be evaluated by the Scala compiler at compile-time.
  *
@@ -82,6 +84,7 @@ package api
  *  }}}
  *
  *  @contentDiagram hideNodes "*Api"
+ *  @group ReflectionAPI
  */
 trait Constants {
   self: Universe =>
@@ -186,7 +189,7 @@ trait Constants {
    */
   implicit val ConstantTag: ClassTag[Constant]
 
-  /** The constructor/deconstructor for `Constant` instances.
+  /** The constructor/extractor for `Constant` instances.
    *  @group Extractors
    */
   val Constant: ConstantExtractor
diff --git a/src/reflect/scala/reflect/api/Exprs.scala b/src/reflect/scala/reflect/api/Exprs.scala
index 45bfddb55d..562b1da8e3 100644
--- a/src/reflect/scala/reflect/api/Exprs.scala
+++ b/src/reflect/scala/reflect/api/Exprs.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
@@ -8,7 +8,10 @@ package api
 
 import scala.reflect.runtime.{universe => ru}
 
-/** A trait that defines strongly-typed tree wrappers and operations on them for use in Scala Reflection.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ * A trait that defines strongly-typed tree wrappers and operations on them for use in Scala Reflection.
  *
  *  `Expr` wraps an abstract syntax tree ([[scala.reflect.api.Trees#Tree]]) and tags it with its type ([[scala.reflect.api.Types#Type]]).
  *
@@ -24,6 +27,8 @@ import scala.reflect.runtime.{universe => ru}
  *  to classes/objects/packages in the expression are re-resolved within the new mirror
  *  (typically using that mirror's classloader). The default universe of an `Expr` is typically
  *  [[scala.reflect.runtime#universe]], the default mirror is typically [[scala.reflect.runtime#currentMirror]].
+ *
+ * @group ReflectionAPI
  */
 trait Exprs { self: Universe =>
 
@@ -103,16 +108,12 @@ trait Exprs { self: Universe =>
      */
     val value: T
 
-    /** TODO how do I doc this? */
     override def canEqual(x: Any) = x.isInstanceOf[Expr[_]]
 
-    /** TODO how do I doc this? */
     override def equals(x: Any) = x.isInstanceOf[Expr[_]] && this.mirror == x.asInstanceOf[Expr[_]].mirror && this.tree == x.asInstanceOf[Expr[_]].tree
 
-    /** TODO how do I doc this? */
     override def hashCode = mirror.hashCode * 31 + tree.hashCode
 
-    /** TODO how do I doc this? */
     override def toString = "Expr["+staticType+"]("+tree+")"
   }
 
diff --git a/src/reflect/scala/reflect/api/FlagSets.scala b/src/reflect/scala/reflect/api/FlagSets.scala
index a7d1ca05a6..4357aec9c9 100644
--- a/src/reflect/scala/reflect/api/FlagSets.scala
+++ b/src/reflect/scala/reflect/api/FlagSets.scala
@@ -4,6 +4,8 @@ package api
 import scala.language.implicitConversions
 
 /**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
  * The trait that defines flag sets and operations on them.
  *
  * `Flag`s are used to provide modifiers for abstract syntax trees that represent definitions
@@ -19,8 +21,8 @@ import scala.language.implicitConversions
  * {{{
  *  ClassDef(Modifiers(NoFlags), newTypeName("C"), Nil, ...)
  * }}}
- * 
- * Here, the flag set is empty. 
+ *
+ * Here, the flag set is empty.
  *
  * To make `C` private, one would write something like:
  * {{{
@@ -34,7 +36,7 @@ import scala.language.implicitConversions
  * }}}
  *
  * The list of all available flags is defined in [[scala.reflect.api.FlagSets#FlagValues]], available via
- * [[scala.reflect.api.FlagSets#Flag]]. (Typically one writes a blanket import for this, e.g.
+ * [[scala.reflect.api.FlagSets#Flag]]. (Typically one writes a wildcard import for this, e.g.
  * `import scala.reflect.runtime.universe.Flag._`).
  *
  * Definition trees are compiled down to symbols, so flags on modifiers of these trees are transformed into flags
@@ -45,9 +47,11 @@ import scala.language.implicitConversions
  * ''Of Note:'' This part of the Reflection API is being considered as a candidate for redesign. It is
  * quite possible that in future releases of the reflection API, flag sets could be replaced with something else.
  *
- * For more details about `FlagSet`s and other aspects of Scala reflection, see the 
+ * For more details about `FlagSet`s and other aspects of Scala reflection, see the
  * [[http://docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]]
  *
+ * @group ReflectionAPI
+ *
  */
 trait FlagSets { self: Universe =>
 
diff --git a/src/reflect/scala/reflect/api/Importers.scala b/src/reflect/scala/reflect/api/Importers.scala
index 4286b2b45c..afc4f2f25d 100644
--- a/src/reflect/scala/reflect/api/Importers.scala
+++ b/src/reflect/scala/reflect/api/Importers.scala
@@ -1,17 +1,21 @@
 package scala.reflect
 package api
 
-/** This trait provides support for importers, a facility to migrate reflection artifacts between universes.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ * This trait provides support for importers, a facility to migrate reflection artifacts between universes.
+ * ''Note: this trait should typically be used only rarely.''
  *
  *  Reflection artifacts, such as [[scala.reflect.api.Symbols Symbols]] and [[scala.reflect.api.Types Types]],
- *  are contained in [[scala.reflect.api.Universes Universe]]s. Typically all processing happens 
- *  within a single `Universe` (e.g. a compile-time macro `Universe` or a runtime reflection `Universe`), but sometimes 
- *  there is a need to migrate artifacts from one `Universe` to another. For example, runtime compilation works by 
- *  importing runtime reflection trees into a runtime compiler universe, compiling the importees and exporting the 
+ *  are contained in [[scala.reflect.api.Universes Universe]]s. Typically all processing happens
+ *  within a single `Universe` (e.g. a compile-time macro `Universe` or a runtime reflection `Universe`), but sometimes
+ *  there is a need to migrate artifacts from one `Universe` to another. For example, runtime compilation works by
+ *  importing runtime reflection trees into a runtime compiler universe, compiling the importees and exporting the
  *  result back.
  *
- *  Reflection artifacts are firmly grounded in their `Universe`s, which is reflected by the fact that types of artifacts 
- *  from different universes are not compatible. By using `Importer`s, however, they be imported from one universe 
+ *  Reflection artifacts are firmly grounded in their `Universe`s, which is reflected by the fact that types of artifacts
+ *  from different universes are not compatible. By using `Importer`s, however, they be imported from one universe
  *  into another. For example, to import `foo.bar.Baz` from the source `Universe` to the target `Universe`,
  *  an importer will first check whether the entire owner chain exists in the target `Universe`.
  *  If it does, then nothing else will be done. Otherwise, the importer will recreate the entire owner chain
@@ -52,6 +56,8 @@ package api
  *    ...
  *  }
  *  }}}
+ *
+ * @group ReflectionAPI
  */
 trait Importers { self: Universe =>
 
diff --git a/src/reflect/scala/reflect/api/JavaMirrors.scala b/src/reflect/scala/reflect/api/JavaMirrors.scala
index df099006b5..b678033e1a 100644
--- a/src/reflect/scala/reflect/api/JavaMirrors.scala
+++ b/src/reflect/scala/reflect/api/JavaMirrors.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package api
 
-/** A refinement of [[scala.reflect.api.Mirror]] for runtime reflection using JVM classloaders.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ * A refinement of [[scala.reflect.api.Mirror]] for runtime reflection using JVM classloaders.
  *
  *  This refinement equips mirrors with reflection capabilities for the JVM. `JavaMirror` can
  *  convert Scala reflection artifacts (symbols and types) into Java reflection artifacts (classes)
@@ -12,6 +15,7 @@ package api
  *  [[http://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html Reflection Guide: Mirrors]]
  *
  *  @groupname JavaMirrors Java Mirrors
+ *  @group ReflectionAPI
  */
 trait JavaMirrors { self: JavaUniverse =>
 
diff --git a/src/reflect/scala/reflect/api/JavaUniverse.scala b/src/reflect/scala/reflect/api/JavaUniverse.scala
index f83692034f..04d091ee9d 100644
--- a/src/reflect/scala/reflect/api/JavaUniverse.scala
+++ b/src/reflect/scala/reflect/api/JavaUniverse.scala
@@ -1,13 +1,18 @@
 package scala.reflect
 package api
 
-/** A refinement of [[scala.reflect.api.Universe]] for runtime reflection using JVM classloaders.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ * A refinement of [[scala.reflect.api.Universe]] for runtime reflection using JVM classloaders.
  *
  *  The refinement consists of an upgrade to the mirror API, which gets extended from [[scala.reflect.api.Mirror]]
  *  to [[scala.reflect.api.JavaMirrors#JavaMirror]].
  *
  *  See the [[http://docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for details on how to use runtime reflection.
+ *
  *  @groupname JavaUniverse Java Mirrors
+ *  @group ReflectionAPI
  *
  *  @contentDiagram hideNodes "*Api"
  */
diff --git a/src/reflect/scala/reflect/api/Mirror.scala b/src/reflect/scala/reflect/api/Mirror.scala
index b1290cc02e..1223326d7c 100644
--- a/src/reflect/scala/reflect/api/Mirror.scala
+++ b/src/reflect/scala/reflect/api/Mirror.scala
@@ -2,16 +2,19 @@ package scala.reflect
 package api
 
 /**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
  * The base class for all mirrors.
  *
  * See [[scala.reflect.api.Mirrors]] or [[docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]]
  * for a complete overview of `Mirror`s.
  *
  * @tparam U the type of the universe this mirror belongs to.
+ *  @group ReflectionAPI
  */
 // Note: Unlike most Scala reflection artifact classes, `Mirror` is not defined as an inner class,
 // so that it can be referenced from outside. For example, [[scala.reflect.api.TypeCreator]] and [[scala.reflect.api.TreeCreator]]
-// reference `Mirror` and also need to be defined outside the cake as they are used by type tags, which can be migrated between 
+// reference `Mirror` and also need to be defined outside the cake as they are used by type tags, which can be migrated between
 // different universes and consequently cannot be bound to a fixed one.
 abstract class Mirror[U <: Universe with Singleton] {
   /** The universe this mirror belongs to.
diff --git a/src/reflect/scala/reflect/api/Mirrors.scala b/src/reflect/scala/reflect/api/Mirrors.scala
index cc1b9762cb..d0d8a37584 100644
--- a/src/reflect/scala/reflect/api/Mirrors.scala
+++ b/src/reflect/scala/reflect/api/Mirrors.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package api
 
-/** This trait provides support for Mirrors in the Scala Reflection API.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ * This trait provides support for Mirrors in the Scala Reflection API.
  *
  * `Mirror`s are a central part of Scala Reflection. All information provided by
  * reflection is made accessible through `Mirror`s. Depending on the type of information
@@ -14,13 +17,13 @@ package api
  * The two flavors of mirrors:
  *
  * <ul>
- * <li>```“Classloader” mirrors```. These mirrors translate names to symbols
+ * <li>'''“Classloader” mirrors'''. These mirrors translate names to symbols
  * (via methods `staticClass`/`staticModule`/`staticPackage`).</li>
- * <li>```"Invoker” mirrors```. These mirrors implement reflective invocations
+ * <li>'''"Invoker” mirrors'''. These mirrors implement reflective invocations
  * (via methods `MethodMirror.apply`, `FieldMirror.get`, etc). These "invoker"
  * mirrors are the types of mirrors that are most commonly used.</li>
  * </ul>
- * 
+ *
  * === Compile-time Mirrors ===
  * Compile-time `Mirror`s make use of only classloader `Mirror`s to load `Symbol`s
  * by name.
@@ -50,7 +53,7 @@ package api
  * lookup symbols. For example, `typeOf[Location.type].termSymbol` (or `typeOf[Location].typeSymbol`
  * if we needed a `ClassSymbol`), which are type safe since we don’t have to use `String`s to lookup
  * the `Symbol`.
- * 
+ *
  * === Runtime Mirrors ===
  *
  * Runtime `Mirror`s make use of both classloader and invoker `Mirror`s.
@@ -59,7 +62,7 @@ package api
  * `ru` is [[scala.reflect.runtime.universe]].
  *
  * The result of a [[scala.reflect.api.JavaMirrors#runtimeMirror]] call is a classloader mirror,
- * of type [[scala.reflect.api.Mirrors#ReflectiveMirror]], which can load symbols by names as 
+ * of type [[scala.reflect.api.Mirrors#ReflectiveMirror]], which can load symbols by names as
  * discussed above (in the “Compile-time” section).
  *
  * A classloader mirror can create invoker mirrors, which include: [[scala.reflect.api.Mirrors#InstanceMirror]],
@@ -202,6 +205,7 @@ package api
  * [[http://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html Reflection Guide: Mirrors]]
  *
  *  @contentDiagram hideNodes "*Api"
+ *  @group ReflectionAPI
  */
 trait Mirrors { self: Universe =>
 
diff --git a/src/reflect/scala/reflect/api/Names.scala b/src/reflect/scala/reflect/api/Names.scala
index 02eb79f8ed..7c12f180a8 100644
--- a/src/reflect/scala/reflect/api/Names.scala
+++ b/src/reflect/scala/reflect/api/Names.scala
@@ -1,21 +1,29 @@
 package scala.reflect
 package api
 
-/** This trait defines Names (a Scala reflection concept) and operations on them.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
  *
- *  Names are simple wrappers for strings. [[scala.reflect.api.Names#Name Name]] has two subtypes [[scala.reflect.api.Names#TermName TermName]] and [[scala.reflect.api.Names#TypeName TypeName]] which
- *  distinguish names of terms (like objects or members) and types. A term and a type of the
- *  same name can co-exist in an object. 
+ * This trait defines `Name`s in Scala Reflection, and operations on them.
  *
- *  === Examples ===
+ *  Names are simple wrappers for strings. [[scala.reflect.api.Names#Name Name]] has two subtypes
+ *  [[scala.reflect.api.Names#TermName TermName]] and [[scala.reflect.api.Names#TypeName TypeName]]
+ *  which distinguish names of terms (like objects or members) and types. A term and a type of the
+ *  same name can co-exist in an object.
  *
- *  To search for the `map` method (which is a term) declared in the `List` class,
- *  use `typeOf[List[_]].member(newTermName("map"))`. To search for a type member, use
- *  newTypeName instead.
+ *  To search for the `map` method (which is a term) declared in the `List` class, one can do:
  *
- *  See the [[docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for more about Scala Reflection.
+ * {{{
+ *   scala> typeOf[List[_]].member(newTermName("map"))
+ *   res0: reflect.runtime.universe.Symbol = method map
+ * }}}
+ *
+ *  To search for a type member, one can follow the same procedure, using `newTypeName` instead.
+ *
+ *  For more information about creating and using `Name`s, see the [[http://docs.scala-lang.org/overviews/reflection/annotations-names-scopes.html Reflection Guide: Annotations, Names, Scopes, and More]]
  *
  *  @contentDiagram hideNodes "*Api"
+ *  @group ReflectionAPI
  */
 trait Names {
   /** An implicit conversion from String to TermName.
diff --git a/src/reflect/scala/reflect/api/Position.scala b/src/reflect/scala/reflect/api/Position.scala
index 61d643b449..63c67627a3 100644
--- a/src/reflect/scala/reflect/api/Position.scala
+++ b/src/reflect/scala/reflect/api/Position.scala
@@ -3,44 +3,18 @@ package api
 
 import scala.reflect.macros.Attachments
 
-/** Position tracks the origin of [[Symbols#Symbol symbols]] and [[Trees#Tree tree nodes]]. They are commonly used when
- *  displaying warnings and errors, to indicate the incorrect point in the program.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
  *
- *  A position indicates the [[source source file]] and an [[point offset]]. A position may be
- *  undefined, which means it's pointing to the [[Positions#NoPosition]] element.
+ * Position tracks the origin of [[Symbols#Symbol symbols]] and [[Trees#Tree tree nodes]]. They are commonly used when
+ * displaying warnings and errors, to indicate the incorrect point in the program.
  *
- *  <b>Please note that this trait may be refactored in future versions of the Scala reflection API.</b>
+ * <b>Please note that this trait may be refactored in future versions of the Scala reflection API.</b>
  *
- *  @see [[http://docs.scala-lang.org/overviews/reflection/names-exprs-scopes-more.html]]
- *
- *  The compiler adds more information to positions, such a ranges in the source file and defines different types of
- *  positions depending on how a symbol or tree node was generated. The guide fully describes compiler-generated positions.
- *
- *  - INV1: A tree with an offset position never contains a child
- *        with a range position
- *  - INV2: If the child of a tree with a range position also has a range position,
- *        then the child's range is contained in the parent's range.
- *  - INV3: Opaque range positions of children of the same node are non-overlapping
- *        (this means their overlap is at most a single point).
- *
- *  The following tests are useful on positions:
- *  `pos.isDefined`     true if position is not a NoPosition,
- *  `pos.isRange`       true if position is a range,
- *  `pos.isOpaqueRange` true if position is an opaque range,
- *
- *  There are also convenience methods, such as
- *  `pos.startOrPoint`,
- *  `pos.endOrPoint`,
- *  `pos.pointOrElse(default)`.
- *  These are less strict about the kind of position on which they can be applied.
- *
- *  The following conversion methods are often used:
- *  `pos.focus`           converts a range position to an offset position, keeping its point;
- *                        returns all other positions unchanged,
- *  `pos.makeTransparent` converts an opaque range position into a transparent one.
- *                        returns all other positions unchanged.
+ * For more information about `Position`s, see the [[http://docs.scala-lang.org/overviews/reflection/annotations-names-scopes.html Reflection Guide: Annotations, Names, Scopes, and More]]
  *
  *  @groupname Common   Commonly used methods
+ *  @group ReflectionAPI
  */
 trait Position extends Attachments {
 
@@ -70,7 +44,7 @@ trait Position extends Attachments {
   def isTransparent: Boolean
 
   /** Is this position a non-transparent range position? */
-    def isOpaqueRange: Boolean
+  def isOpaqueRange: Boolean
 
   /** If opaque range, make this position transparent. */
   def makeTransparent: Pos
diff --git a/src/reflect/scala/reflect/api/Positions.scala b/src/reflect/scala/reflect/api/Positions.scala
index 8d8a0081cc..87f00fdb88 100644
--- a/src/reflect/scala/reflect/api/Positions.scala
+++ b/src/reflect/scala/reflect/api/Positions.scala
@@ -1,11 +1,15 @@
 package scala.reflect
 package api
 
-/** This trait defines the concept of positions and operations on them.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
  *
- *  @see [[scala.reflect.api.Position]]
+ * This trait defines the concept of positions and operations on them.
  *
- *  @contentDiagram hideNodes "*Api"
+ * @see [[scala.reflect.api.Position]]
+ *
+ * @contentDiagram hideNodes "*Api"
+ * @group ReflectionAPI
  */
 trait Positions {
   self: Universe =>
diff --git a/src/reflect/scala/reflect/api/Printers.scala b/src/reflect/scala/reflect/api/Printers.scala
index 1e8161aeef..85ddcc6523 100644
--- a/src/reflect/scala/reflect/api/Printers.scala
+++ b/src/reflect/scala/reflect/api/Printers.scala
@@ -3,14 +3,17 @@ package api
 
 import java.io.{ PrintWriter, StringWriter }
 
-/** Utilities for nicely printing [[scala.reflect.api.Trees]] and [[scala.reflect.api.Types]].
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
  *
- *  === Printing Trees ===
- *  The method `show` displays the "prettified" representation of reflection artifacts.
- *  This representation provides one with the desugared Java representation of Scala code. 
- *  For example:
+ * Utilities for nicely printing [[scala.reflect.api.Trees]] and [[scala.reflect.api.Types]].
  *
- *  {{{
+ * === Printing Trees ===
+ * The method `show` displays the "prettified" representation of reflection artifacts.
+ * This representation provides one with the desugared Java representation of Scala code.
+ * For example:
+ *
+ * {{{
  *  scala> import scala.reflect.runtime.universe._
  *  import scala.reflect.runtime.universe._
  *
@@ -30,7 +33,7 @@ import java.io.{ PrintWriter, StringWriter }
  *    ()
  *  }
  * }}}
- * 
+ *
  * The method `showRaw` displays internal structure of a given reflection object
  * as a Scala abstract syntax tree (AST), the representation that the Scala typechecker
  * operates on.
@@ -54,7 +57,7 @@ import java.io.{ PrintWriter, StringWriter }
  *          Literal(Constant(2))))))),
  *    Literal(Constant(())))
  * }}}
- * 
+ *
  * The method `showRaw` can also print [[scala.reflect.api.Types]] next to the artifacts
  * being inspected
  * {{{
@@ -89,7 +92,7 @@ import java.io.{ PrintWriter, StringWriter }
  *
  *  === Printing Types ===
  *
- * The method `show` 
+ * The method `show`
  *  {{{
  *  scala> import scala.reflect.runtime.universe._
  *  import scala.reflect.runtime.universe._
@@ -116,17 +119,20 @@ import java.io.{ PrintWriter, StringWriter }
  *
  * `printIds` and/or `printKinds` can additionally be supplied as arguments in a call to
  * `showRaw` which additionally shows the unique identifiers of symbols.
+ *
+ * {{{
  *  scala> showRaw(tpe, printIds = true, printKinds = true)
  *  res2: String = RefinedType(
  *    List(TypeRef(ThisType(scala#2043#PK), newTypeName("AnyRef")#691#TPE, List())),
  *    Scope(
  *      newTermName("x")#2540#METH,
  *      newTermName("y")#2541#GET))
- *  }}}
+ * }}}
  *
- * For more details about `Printer`s and other aspects of Scala reflection, see the 
+ * For more details about `Printer`s and other aspects of Scala reflection, see the
  * [[http://docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]]
  *
+ *  @group ReflectionAPI
  */
 trait Printers { self: Universe =>
 
diff --git a/src/reflect/scala/reflect/api/Scopes.scala b/src/reflect/scala/reflect/api/Scopes.scala
index 80683c8e76..7f9799393c 100644
--- a/src/reflect/scala/reflect/api/Scopes.scala
+++ b/src/reflect/scala/reflect/api/Scopes.scala
@@ -1,19 +1,24 @@
 package scala.reflect
 package api
 
-/** This trait provides support for scopes in the reflection API.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
  *
- *  A scope object generally maps names to symbols available in a corresponding lexical scope.
- *  Scopes can be nested. The base type exposed to the reflection API, however,
- *  only exposes a minimal interface, representing a scope as an iterable of symbols.
+ * This trait provides support for scopes in the reflection API.
  *
- *  For rare occasions when it is necessary to create a scope manually,
- *  e.g., to populate members of [[scala.reflect.api.Types#RefinedType]],
- *  there is the `newScopeWith` function.
+ * A scope object generally maps names to symbols available in a corresponding lexical scope.
+ * Scopes can be nested. The base type exposed to the reflection API, however,
+ * only exposes a minimal interface, representing a scope as an iterable of symbols.
  *
- *  Additional functionality is exposed in member scopes that are returned by
- *  `members` and `declarations` defined in [[scala.reflect.api.Types#TypeApi]].
- *  Such scopes support the `sorted` method, which sorts members in declaration order.
+ * For rare occasions when it is necessary to create a scope manually,
+ * e.g., to populate members of [[scala.reflect.api.Types#RefinedType]],
+ * there is the `newScopeWith` function.
+ *
+ * Additional functionality is exposed in member scopes that are returned by
+ * `members` and `declarations` defined in [[scala.reflect.api.Types#TypeApi]].
+ * Such scopes support the `sorted` method, which sorts members in declaration order.
+ *
+ * @group ReflectionAPI
  */
 trait Scopes { self: Universe =>
 
diff --git a/src/reflect/scala/reflect/api/StandardDefinitions.scala b/src/reflect/scala/reflect/api/StandardDefinitions.scala
index a31a501357..721b0bc7f2 100644
--- a/src/reflect/scala/reflect/api/StandardDefinitions.scala
+++ b/src/reflect/scala/reflect/api/StandardDefinitions.scala
@@ -1,15 +1,20 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 package scala.reflect
 package api
 
-/** All Scala standard symbols and types.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
  *
- * These standard definitions can accessed to using `definitions`. 
- * They're typically imported with a blanket import `import definitions`, and are
+ * All Scala standard symbols and types.
+ *
+ * These standard definitions can accessed to using `definitions`.
+ * They're typically imported with a wildcard import, `import definitions._`, and are
  * listed in [[scala.reflect.api.StandardDefinitions#DefinitionsApi]].
+ *
+ *  @group ReflectionAPI
  */
 trait StandardDefinitions {
   self: Universe =>
diff --git a/src/reflect/scala/reflect/api/StandardNames.scala b/src/reflect/scala/reflect/api/StandardNames.scala
index fc18c02706..4886e4f8f7 100644
--- a/src/reflect/scala/reflect/api/StandardNames.scala
+++ b/src/reflect/scala/reflect/api/StandardNames.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
-* Copyright 2005-2012 LAMP/EPFL
+* Copyright 2005-2013 LAMP/EPFL
 * @author  Martin Odersky
 */
 package scala.reflect
@@ -11,6 +11,8 @@ package api
 //    Otherwise you'd better not - reflection API should stay minimalistic.
 
 /**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
  *  Standard names are names that are essential to creating trees or to reflecting Scala artifacts.
  *  For example, `CONSTRUCTOR` (aka `<init>` on JVM) is necessary to create and invoke constructors.
  *
@@ -20,6 +22,7 @@ package api
  *
  *  The API for names in Scala reflection.
  *  @groupname StandardNames Standard Names
+ *  @group ReflectionAPI
  */
 trait StandardNames {
   self: Universe =>
diff --git a/src/reflect/scala/reflect/api/Symbols.scala b/src/reflect/scala/reflect/api/Symbols.scala
index 993cbd97a5..b53c700701 100644
--- a/src/reflect/scala/reflect/api/Symbols.scala
+++ b/src/reflect/scala/reflect/api/Symbols.scala
@@ -1,25 +1,57 @@
 package scala.reflect
 package api
 
-/** This trait defines symbols and operations on them.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  This trait defines symbols and operations on them.
  *
  *  Symbols are used to establish bindings between a name and the entity it refers to, such as a class or a method.
  *  Anything you define and can give a name to in Scala has an associated symbol.
  *
+ *  Symbols contain all available information about the declaration of an entity (class/object/trait etc.) or a
+ *  member (vals/vars/defs etc.), and as such are an integral abstraction central to both runtime
+ *  reflection and macros.
+ *
+ *  A symbol can provide a wealth of information ranging from the basic `name` method available on all symbols to
+ *  other, more involved, concepts such as getting the `baseClasses` from `ClassSymbol`. Other common use cases of
+ *  symbols include inspecting members' signatures, getting type parameters of a class, getting the parameter type
+ *  of a method or finding out the type of a field.
+ *
+ *  Example usage of runtime reflection; getting a method's type signature:
+ *  {{{
+ *    scala> import scala.reflect.runtime.universe._
+ *    import scala.reflect.runtime.universe._
+ *
+ *    scala> class C[T] { def test[U](x: T)(y: U): Int = ??? }
+ *    defined class C
+ *
+ *    scala> val test = typeOf[C[Int]].member(newTermName("test")).asMethod
+ *    test: reflect.runtime.universe.MethodSymbol = method test
+ *
+ *    scala> test.typeSignature
+ *    res0: reflect.runtime.universe.Type = [U](x: T)(y: U)scala.Int
+ *  }}}
+ *
+ *  Symbols are organized in a hierarchy. For example, a symbol that represents a parameter of a method is owned by
+ *  the corresponding method symbol, a method symbol is owned by its enclosing class, a class is owned by a
+ *  containing package and so on.
+ *
  *  Certain types of tree nodes, such as [[Trees#Ident Ident]] (references to identifiers) and
  *  [[Trees#Select Select]] (references to members) expose method [[Trees.SymTreeApi.symbol `symbol`]]
  *  to obtain the symbol that represents their declaration. During the typechecking phase, the compiler looks up the
  *  symbol based on the name and scope and sets the [[Trees.SymTreeApi.symbol `symbol` field]] of tree nodes.
  *
- *  @contentDiagram hideNodes "*Api"
+ *  For more information about `Symbol` usage and attached intricacies, see the [[http://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html Reflection Guide: Symbols]]
  *
- *  @see [[http://docs.scala-lang.org/overviews/reflection/overview.html]]
+ *  @group ReflectionAPI
  *
- *  The Reflection Guide provides more details on symbol usage and attached intricacies.
+ *  @contentDiagram hideNodes "*Api"
  *
  *  @define SYMACCESSORS Class [[Symbol]] defines `isXXX` test methods such as `isPublic` or `isFinal`, `params` and
  *  `returnType` methods for method symbols, `baseClasses` for class symbols and so on. Some of these methods don't
  *  make sense for certain subclasses of `Symbol` and return `NoSymbol`, `Nil` or other empty values.
+ *
  */
 trait Symbols { self: Universe =>
 
diff --git a/src/reflect/scala/reflect/api/TagInterop.scala b/src/reflect/scala/reflect/api/TagInterop.scala
index 4e43f59706..5de811578e 100644
--- a/src/reflect/scala/reflect/api/TagInterop.scala
+++ b/src/reflect/scala/reflect/api/TagInterop.scala
@@ -1,7 +1,12 @@
 package scala.reflect
 package api
 
-/** This trait provides type tag <-> manifest interoperability.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  This trait provides type tag <-> manifest interoperability.
+ *  @group ReflectionAPI
+ *
  *  @groupname TagInterop TypeTag and Manifest Interoperability
  */
 trait TagInterop { self: Universe =>
diff --git a/src/reflect/scala/reflect/api/TreeCreator.scala b/src/reflect/scala/reflect/api/TreeCreator.scala
index cba90b72e6..6969418470 100644
--- a/src/reflect/scala/reflect/api/TreeCreator.scala
+++ b/src/reflect/scala/reflect/api/TreeCreator.scala
@@ -4,6 +4,8 @@ package api
 /** This is an internal implementation class.
  *
  * This class is used internally by Scala Reflection, and is not recommended for use in client code.
+ *
+ *  @group ReflectionAPI
  */
 abstract class TreeCreator {
   def apply[U <: Universe with Singleton](m: scala.reflect.api.Mirror[U]): U # Tree
diff --git a/src/reflect/scala/reflect/api/Trees.scala b/src/reflect/scala/reflect/api/Trees.scala
index bcb1d0031f..c98107f9b5 100644
--- a/src/reflect/scala/reflect/api/Trees.scala
+++ b/src/reflect/scala/reflect/api/Trees.scala
@@ -1,32 +1,48 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 package scala.reflect
 package api
 
-/** This trait defines the node types used in Scala abstract syntax trees (AST) and operations on them.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
  *
-*  All tree node types are sub types of [[scala.reflect.api.Trees#Tree Tree]].
+ * This trait defines the node types used in Scala abstract syntax trees (AST) and operations on them.
+ *
+ * Trees are the basis for Scala's abstract syntax that is used to represent programs. They are also called
+ * abstract syntax trees and commonly abbreviated as ASTs.
+ *
+ * In Scala reflection, APIs that produce or use `Tree`s are:
+ *
+ *   - '''Annotations''' which use trees to represent their arguments, exposed in [[scala.reflect.api.Annotations#scalaArgs Annotation.scalaArgs]].
+ *   - '''[[scala.reflect.api.Universe#reify reify]]''', a special method on [[scala.reflect.api.Universe]] that takes an expression and returns an AST which represents the expression.
+ *   - '''Macros and runtime compilation with toolboxes''' which both use trees as their program representation medium.
  *
  *  Trees are immutable, except for three fields
  *  [[Trees#TreeApi.pos pos]], [[Trees#TreeApi.symbol symbol]], and [[Trees#TreeApi.tpe tpe]], which are assigned when a tree is typechecked
  *  to attribute it with the information gathered by the typechecker.
  *
- *  [[scala.reflect.api.Universe#reify reify]] can be used to get the tree for a given Scala expression.
+ *  === Examples ===
  *
- *  [[scala.reflect.api.Universe#showRaw showRaw]] can be used to get a readable representation of a tree.
+ *  The following creates an AST representing a literal 5 in Scala source code:
+ *  {{{
+ *    Literal(Constant(5))
+ *  }}}
  *
- *  === Examples ===
- * `Literal(Constant(5))` creates an AST representing a literal 5 in Scala source code.
+ *  The following creates an AST representing `print("Hello World")`:
+ *  {{{
+ *    Apply(Select(Select(This(newTypeName("scala")), newTermName("Predef")), newTermName("print")), List(Literal(Constant("Hello World"))))
+ *  }}}
  *
- * `Apply(Select(Select(This(newTypeName("scala")), newTermName("Predef")), newTermName("print")), List(Literal(Constant("Hello World"))))`
- * creates an AST representing `print("Hello World")`.
+ *  The following creates an AST from a literal 5, and then uses `showRaw` to print it in a readable format.
+ *  {{{
+ *    import scala.reflect.runtime.universe.{ reify, showRaw }
+ *    print( showRaw( reify{5}.tree ) )` // prints Literal(Constant(5))
+ *  }}}
  *
- * `import scala.reflect.runtime.universe.{reify,showRaw}`
- * `print( showRaw( reify{5}.tree ) )` // prints Literal(Constant(5))
+ *  For more information about `Tree`s, see the [[http://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html Reflection Guide: Symbols, Trees, Types]].
  *
- *  @see [[http://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html#trees]].
  *  @groupname Traversal Tree Traversal and Transformation
  *  @groupprio Traversal 1
  *  @groupprio Factories 1
@@ -34,6 +50,7 @@ package api
  *  @groupprio Copying   1
  *
  *  @contentDiagram hideNodes "*Api"
+ *  @group ReflectionAPI
  */
 trait Trees { self: Universe =>
 
@@ -346,7 +363,7 @@ trait Trees { self: Universe =>
    */
   implicit val PackageDefTag: ClassTag[PackageDef]
 
-  /** The constructor/deconstructor for `PackageDef` instances.
+  /** The constructor/extractor for `PackageDef` instances.
    *  @group Extractors
    */
   val PackageDef: PackageDefExtractor
@@ -405,7 +422,7 @@ trait Trees { self: Universe =>
    */
   implicit val ClassDefTag: ClassTag[ClassDef]
 
-  /** The constructor/deconstructor for `ClassDef` instances.
+  /** The constructor/extractor for `ClassDef` instances.
    *  @group Extractors
    */
   val ClassDef: ClassDefExtractor
@@ -456,7 +473,7 @@ trait Trees { self: Universe =>
    */
   implicit val ModuleDefTag: ClassTag[ModuleDef]
 
-  /** The constructor/deconstructor for `ModuleDef` instances.
+  /** The constructor/extractor for `ModuleDef` instances.
    *  @group Extractors
    */
   val ModuleDef: ModuleDefExtractor
@@ -539,7 +556,7 @@ trait Trees { self: Universe =>
    */
   implicit val ValDefTag: ClassTag[ValDef]
 
-  /** The constructor/deconstructor for `ValDef` instances.
+  /** The constructor/extractor for `ValDef` instances.
    *  @group Extractors
    */
   val ValDef: ValDefExtractor
@@ -594,7 +611,7 @@ trait Trees { self: Universe =>
    */
   implicit val DefDefTag: ClassTag[DefDef]
 
-  /** The constructor/deconstructor for `DefDef` instances.
+  /** The constructor/extractor for `DefDef` instances.
    *  @group Extractors
    */
   val DefDef: DefDefExtractor
@@ -649,7 +666,7 @@ trait Trees { self: Universe =>
    */
   implicit val TypeDefTag: ClassTag[TypeDef]
 
-  /** The constructor/deconstructor for `TypeDef` instances.
+  /** The constructor/extractor for `TypeDef` instances.
    *  @group Extractors
    */
   val TypeDef: TypeDefExtractor
@@ -714,7 +731,7 @@ trait Trees { self: Universe =>
    */
   implicit val LabelDefTag: ClassTag[LabelDef]
 
-  /** The constructor/deconstructor for `LabelDef` instances.
+  /** The constructor/extractor for `LabelDef` instances.
    *  @group Extractors
    */
   val LabelDef: LabelDefExtractor
@@ -776,7 +793,7 @@ trait Trees { self: Universe =>
    */
   implicit val ImportSelectorTag: ClassTag[ImportSelector]
 
-  /** The constructor/deconstructor for `ImportSelector` instances.
+  /** The constructor/extractor for `ImportSelector` instances.
    *  @group Extractors
    */
   val ImportSelector: ImportSelectorExtractor
@@ -828,7 +845,7 @@ trait Trees { self: Universe =>
    */
   implicit val ImportTag: ClassTag[Import]
 
-  /** The constructor/deconstructor for `Import` instances.
+  /** The constructor/extractor for `Import` instances.
    *  @group Extractors
    */
   val Import: ImportExtractor
@@ -886,7 +903,7 @@ trait Trees { self: Universe =>
    */
   implicit val TemplateTag: ClassTag[Template]
 
-  /** The constructor/deconstructor for `Template` instances.
+  /** The constructor/extractor for `Template` instances.
    *  @group Extractors
    */
   val Template: TemplateExtractor
@@ -944,7 +961,7 @@ trait Trees { self: Universe =>
    */
   implicit val BlockTag: ClassTag[Block]
 
-  /** The constructor/deconstructor for `Block` instances.
+  /** The constructor/extractor for `Block` instances.
    *  @group Extractors
    */
   val Block: BlockExtractor
@@ -989,7 +1006,7 @@ trait Trees { self: Universe =>
    */
   implicit val CaseDefTag: ClassTag[CaseDef]
 
-  /** The constructor/deconstructor for `CaseDef` instances.
+  /** The constructor/extractor for `CaseDef` instances.
    *  @group Extractors
    */
   val CaseDef: CaseDefExtractor
@@ -1042,7 +1059,7 @@ trait Trees { self: Universe =>
    */
   implicit val AlternativeTag: ClassTag[Alternative]
 
-  /** The constructor/deconstructor for `Alternative` instances.
+  /** The constructor/extractor for `Alternative` instances.
    *  @group Extractors
    */
   val Alternative: AlternativeExtractor
@@ -1080,7 +1097,7 @@ trait Trees { self: Universe =>
    */
   implicit val StarTag: ClassTag[Star]
 
-  /** The constructor/deconstructor for `Star` instances.
+  /** The constructor/extractor for `Star` instances.
    *  @group Extractors
    */
   val Star: StarExtractor
@@ -1121,7 +1138,7 @@ trait Trees { self: Universe =>
    */
   implicit val BindTag: ClassTag[Bind]
 
-  /** The constructor/deconstructor for `Bind` instances.
+  /** The constructor/extractor for `Bind` instances.
    *  @group Extractors
    */
   val Bind: BindExtractor
@@ -1190,7 +1207,7 @@ trait Trees { self: Universe =>
    */
   implicit val UnApplyTag: ClassTag[UnApply]
 
-  /** The constructor/deconstructor for `UnApply` instances.
+  /** The constructor/extractor for `UnApply` instances.
    *  @group Extractors
    */
   val UnApply: UnApplyExtractor
@@ -1232,7 +1249,7 @@ trait Trees { self: Universe =>
    */
   implicit val FunctionTag: ClassTag[Function]
 
-  /** The constructor/deconstructor for `Function` instances.
+  /** The constructor/extractor for `Function` instances.
    *  @group Extractors
    */
   val Function: FunctionExtractor
@@ -1276,7 +1293,7 @@ trait Trees { self: Universe =>
    */
   implicit val AssignTag: ClassTag[Assign]
 
-  /** The constructor/deconstructor for `Assign` instances.
+  /** The constructor/extractor for `Assign` instances.
    *  @group Extractors
    */
   val Assign: AssignExtractor
@@ -1318,7 +1335,7 @@ trait Trees { self: Universe =>
    */
   implicit val AssignOrNamedArgTag: ClassTag[AssignOrNamedArg]
 
-  /** The constructor/deconstructor for `AssignOrNamedArg` instances.
+  /** The constructor/extractor for `AssignOrNamedArg` instances.
    *  @group Extractors
    */
   val AssignOrNamedArg: AssignOrNamedArgExtractor
@@ -1365,7 +1382,7 @@ trait Trees { self: Universe =>
    */
   implicit val IfTag: ClassTag[If]
 
-  /** The constructor/deconstructor for `If` instances.
+  /** The constructor/extractor for `If` instances.
    *  @group Extractors
    */
   val If: IfExtractor
@@ -1422,7 +1439,7 @@ trait Trees { self: Universe =>
    */
   implicit val MatchTag: ClassTag[Match]
 
-  /** The constructor/deconstructor for `Match` instances.
+  /** The constructor/extractor for `Match` instances.
    *  @group Extractors
    */
   val Match: MatchExtractor
@@ -1463,7 +1480,7 @@ trait Trees { self: Universe =>
    */
   implicit val ReturnTag: ClassTag[Return]
 
-  /** The constructor/deconstructor for `Return` instances.
+  /** The constructor/extractor for `Return` instances.
    *  @group Extractors
    */
   val Return: ReturnExtractor
@@ -1501,7 +1518,7 @@ trait Trees { self: Universe =>
    */
   implicit val TryTag: ClassTag[Try]
 
-  /** The constructor/deconstructor for `Try` instances.
+  /** The constructor/extractor for `Try` instances.
    *  @group Extractors
    */
   val Try: TryExtractor
@@ -1545,7 +1562,7 @@ trait Trees { self: Universe =>
    */
   implicit val ThrowTag: ClassTag[Throw]
 
-  /** The constructor/deconstructor for `Throw` instances.
+  /** The constructor/extractor for `Throw` instances.
    *  @group Extractors
    */
   val Throw: ThrowExtractor
@@ -1581,7 +1598,7 @@ trait Trees { self: Universe =>
    */
   implicit val NewTag: ClassTag[New]
 
-  /** The constructor/deconstructor for `New` instances.
+  /** The constructor/extractor for `New` instances.
    *  @group Extractors
    */
   val New: NewExtractor
@@ -1628,7 +1645,7 @@ trait Trees { self: Universe =>
    */
   implicit val TypedTag: ClassTag[Typed]
 
-  /** The constructor/deconstructor for `Typed` instances.
+  /** The constructor/extractor for `Typed` instances.
    *  @group Extractors
    */
   val Typed: TypedExtractor
@@ -1694,7 +1711,7 @@ trait Trees { self: Universe =>
    */
   implicit val TypeApplyTag: ClassTag[TypeApply]
 
-  /** The constructor/deconstructor for `TypeApply` instances.
+  /** The constructor/extractor for `TypeApply` instances.
    *  @group Extractors
    */
   val TypeApply: TypeApplyExtractor
@@ -1728,7 +1745,7 @@ trait Trees { self: Universe =>
    */
   implicit val ApplyTag: ClassTag[Apply]
 
-  /** The constructor/deconstructor for `Apply` instances.
+  /** The constructor/extractor for `Apply` instances.
    *  @group Extractors
    */
   val Apply: ApplyExtractor
@@ -1771,7 +1788,7 @@ trait Trees { self: Universe =>
    */
   implicit val SuperTag: ClassTag[Super]
 
-  /** The constructor/deconstructor for `Super` instances.
+  /** The constructor/extractor for `Super` instances.
    *  @group Extractors
    */
   val Super: SuperExtractor
@@ -1823,7 +1840,7 @@ trait Trees { self: Universe =>
    */
   implicit val ThisTag: ClassTag[This]
 
-  /** The constructor/deconstructor for `This` instances.
+  /** The constructor/extractor for `This` instances.
    *  @group Extractors
    */
   val This: ThisExtractor
@@ -1864,7 +1881,7 @@ trait Trees { self: Universe =>
    */
   implicit val SelectTag: ClassTag[Select]
 
-  /** The constructor/deconstructor for `Select` instances.
+  /** The constructor/extractor for `Select` instances.
    *  @group Extractors
    */
   val Select: SelectExtractor
@@ -1903,7 +1920,7 @@ trait Trees { self: Universe =>
    */
   implicit val IdentTag: ClassTag[Ident]
 
-  /** The constructor/deconstructor for `Ident` instances.
+  /** The constructor/extractor for `Ident` instances.
    *  @group Extractors
    */
   val Ident: IdentExtractor
@@ -1948,7 +1965,7 @@ trait Trees { self: Universe =>
    */
   implicit val ReferenceToBoxedTag: ClassTag[ReferenceToBoxed]
 
-  /** The constructor/deconstructor for `ReferenceToBoxed` instances.
+  /** The constructor/extractor for `ReferenceToBoxed` instances.
    *  @group Extractors
    */
   val ReferenceToBoxed: ReferenceToBoxedExtractor
@@ -1998,7 +2015,7 @@ trait Trees { self: Universe =>
    */
   implicit val LiteralTag: ClassTag[Literal]
 
-  /** The constructor/deconstructor for `Literal` instances.
+  /** The constructor/extractor for `Literal` instances.
    *  @group Extractors
    */
   val Literal: LiteralExtractor
@@ -2037,7 +2054,7 @@ trait Trees { self: Universe =>
    */
   implicit val AnnotatedTag: ClassTag[Annotated]
 
-  /** The constructor/deconstructor for `Annotated` instances.
+  /** The constructor/extractor for `Annotated` instances.
    *  @group Extractors
    */
   val Annotated: AnnotatedExtractor
@@ -2077,7 +2094,7 @@ trait Trees { self: Universe =>
    */
   implicit val SingletonTypeTreeTag: ClassTag[SingletonTypeTree]
 
-  /** The constructor/deconstructor for `SingletonTypeTree` instances.
+  /** The constructor/extractor for `SingletonTypeTree` instances.
    *  @group Extractors
    */
   val SingletonTypeTree: SingletonTypeTreeExtractor
@@ -2114,7 +2131,7 @@ trait Trees { self: Universe =>
    */
   implicit val SelectFromTypeTreeTag: ClassTag[SelectFromTypeTree]
 
-  /** The constructor/deconstructor for `SelectFromTypeTree` instances.
+  /** The constructor/extractor for `SelectFromTypeTree` instances.
    *  @group Extractors
    */
   val SelectFromTypeTree: SelectFromTypeTreeExtractor
@@ -2155,7 +2172,7 @@ trait Trees { self: Universe =>
    */
   implicit val CompoundTypeTreeTag: ClassTag[CompoundTypeTree]
 
-  /** The constructor/deconstructor for `CompoundTypeTree` instances.
+  /** The constructor/extractor for `CompoundTypeTree` instances.
    *  @group Extractors
    */
   val CompoundTypeTree: CompoundTypeTreeExtractor
@@ -2191,7 +2208,7 @@ trait Trees { self: Universe =>
    */
   implicit val AppliedTypeTreeTag: ClassTag[AppliedTypeTree]
 
-  /** The constructor/deconstructor for `AppliedTypeTree` instances.
+  /** The constructor/extractor for `AppliedTypeTree` instances.
    *  @group Extractors
    */
   val AppliedTypeTree: AppliedTypeTreeExtractor
@@ -2230,7 +2247,7 @@ trait Trees { self: Universe =>
    */
   implicit val TypeBoundsTreeTag: ClassTag[TypeBoundsTree]
 
-  /** The constructor/deconstructor for `TypeBoundsTree` instances.
+  /** The constructor/extractor for `TypeBoundsTree` instances.
    *  @group Extractors
    */
   val TypeBoundsTree: TypeBoundsTreeExtractor
@@ -2273,7 +2290,7 @@ trait Trees { self: Universe =>
    */
   implicit val ExistentialTypeTreeTag: ClassTag[ExistentialTypeTree]
 
-  /** The constructor/deconstructor for `ExistentialTypeTree` instances.
+  /** The constructor/extractor for `ExistentialTypeTree` instances.
    *  @group Extractors
    */
   val ExistentialTypeTree: ExistentialTypeTreeExtractor
@@ -2316,7 +2333,7 @@ trait Trees { self: Universe =>
    */
   implicit val TypeTreeTag: ClassTag[TypeTree]
 
-  /** The constructor/deconstructor for `TypeTree` instances.
+  /** The constructor/extractor for `TypeTree` instances.
    *  @group Extractors
    */
   val TypeTree: TypeTreeExtractor
@@ -2909,7 +2926,7 @@ trait Trees { self: Universe =>
       Modifiers(flags, privateWithin, f(annotations))
   }
 
-  /** The constructor/deconstructor for `Modifiers` instances.
+  /** The constructor/extractor for `Modifiers` instances.
    *  @group Traversal
    */
   val Modifiers: ModifiersCreator
diff --git a/src/reflect/scala/reflect/api/TypeCreator.scala b/src/reflect/scala/reflect/api/TypeCreator.scala
index 9c386f2939..24271cb48d 100644
--- a/src/reflect/scala/reflect/api/TypeCreator.scala
+++ b/src/reflect/scala/reflect/api/TypeCreator.scala
@@ -4,6 +4,8 @@ package api
 /** A mirror-aware factory for types.
  *
  * This class is used internally by Scala Reflection, and is not recommended for use in client code.
+ *
+ * @group ReflectionAPI
  */
 abstract class TypeCreator {
   def apply[U <: Universe with Singleton](m: scala.reflect.api.Mirror[U]): U # Type
diff --git a/src/reflect/scala/reflect/api/TypeTags.scala b/src/reflect/scala/reflect/api/TypeTags.scala
index 812d5199fc..e988971ace 100644
--- a/src/reflect/scala/reflect/api/TypeTags.scala
+++ b/src/reflect/scala/reflect/api/TypeTags.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
@@ -10,13 +10,6 @@ package api
 import java.lang.{ Class => jClass }
 import scala.language.implicitConversions
 
-/*
- * TODO
- * add @see to docs about universes
- * [Eugene++] also mention sensitivity to prefixes, i.e. that rb.TypeTag is different from ru.TypeTag
- * [Chris++] tag.in(some mirror) or expr.in(some mirror)  (does not work for tag and exprs in macros)
- * Backwards compat item1: [Eugene++] it might be useful, though, to guard against abstractness of the incoming type.
- */
 /**
  * A `TypeTag[T]` encapsulates the runtime type representation of some type `T`.
  * Like [[scala.reflect.Manifest]], the prime use case of `TypeTag`s is to give access
@@ -95,7 +88,7 @@ import scala.language.implicitConversions
  *   scala> paramInfo(List(1, 2))
  *   type of List(1, 2) has type arguments List(Int)
  * }}}
- * 
+ *
  * === `WeakTypeTag`s ===
  *
  *`WeakTypeTag[T]` generalizes `TypeTag[T]`. Unlike a regular `TypeTag`, components of
@@ -154,7 +147,7 @@ import scala.language.implicitConversions
  * [[http://docs.scala-lang.org/overviews/reflection/typetags-manifests.html Reflection Guide: TypeTags]]
  *
  * @see [[scala.reflect.ClassTag]], [[scala.reflect.api.TypeTags#TypeTag]], [[scala.reflect.api.TypeTags#WeakTypeTag]]
- * @group TypeTags Type Tags
+ * @group ReflectionAPI
  */
 trait TypeTags { self: Universe =>
 
@@ -196,16 +189,12 @@ trait TypeTags { self: Universe =>
      */
     def tpe: Type
 
-    // TODO how do I doc this?
     override def canEqual(x: Any) = x.isInstanceOf[WeakTypeTag[_]]
 
-    // TODO how do I doc this?
     override def equals(x: Any) = x.isInstanceOf[WeakTypeTag[_]] && this.mirror == x.asInstanceOf[WeakTypeTag[_]].mirror && this.tpe == x.asInstanceOf[WeakTypeTag[_]].tpe
 
-    // TODO how do I doc this?
     override def hashCode = mirror.hashCode * 31 + tpe.hashCode
 
-    // TODO how do I doc this?
     override def toString = "WeakTypeTag[" + tpe + "]"
   }
 
@@ -279,16 +268,12 @@ trait TypeTags { self: Universe =>
      */
     override def in[U <: Universe with Singleton](otherMirror: scala.reflect.api.Mirror[U]): U # TypeTag[T]
 
-    /** TODO how do I doc this? */
     override def canEqual(x: Any) = x.isInstanceOf[TypeTag[_]]
 
-    /** TODO how do I doc this? */
     override def equals(x: Any) = x.isInstanceOf[TypeTag[_]] && this.mirror == x.asInstanceOf[TypeTag[_]].mirror && this.tpe == x.asInstanceOf[TypeTag[_]].tpe
 
-    /** TODO how do I doc this? */
     override def hashCode = mirror.hashCode * 31 + tpe.hashCode
 
-    /** TODO how do I doc this? */
     override def toString = "TypeTag[" + tpe + "]"
   }
 
diff --git a/src/reflect/scala/reflect/api/Types.scala b/src/reflect/scala/reflect/api/Types.scala
index 7b8cf592ff..143438b8f5 100644
--- a/src/reflect/scala/reflect/api/Types.scala
+++ b/src/reflect/scala/reflect/api/Types.scala
@@ -1,69 +1,52 @@
 package scala.reflect
 package api
 
-/** A trait that defines types and operations on them.
+/**
+ *  <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
  *
- *  Type instances represent information about the type of a corresponding symbol. This includes its members
- *  (methods, fields, type parameters, nested classes, traits, etc) either declared directly or inherited, its base types,
- *  its erasure and so on. Types also provide operation to test for type conformance or euqivalence or for widening.
+ *  A trait that defines types and operations on them.
  *
- *  === Instantiating types ===
+ *  Type instances represent information about the type of a corresponding symbol. This includes its members
+ *  (methods, fields, type parameters, nested classes, traits, etc.) either declared directly or inherited, its base types,
+ *  its erasure and so on. Types also provide operations to test for type conformance or equivalence or for widening.
  *
- *  There are three ways to instantiate types. The simplest one involves the [[scala.reflect.api.TypeTags#typeOf]] method,
- *  which takes a type argument and produces a `Type` instance that represents that argument. For example, `typeOf[List[Int]]`
- *  produces a [[scala.reflect.api.Types#TypeRef]], which corresponds to a type `List` applied to a type argument `Int`.
- *  Method `typeOf` does not work for types with type parameters, such as `typeOf[List[A]]` where `A` is a type variable.
- *  In this case, use [[scala.reflect.api.TypeTags#weakTypeOf]] instead. Refer to [[scala.reflect.api.TypeTags the type tags page]] to find out
- *  more about this distinction.
+ *  To instantiate a type, most of the time, the [[scala.reflect.api.TypeTags#typeOf]] method can be used. It takes
+ *  a type argument and produces a `Type` instance which represents that argument. For example:
  *
- *  `typeOf` requires spelling out a type explicitly, but there's also a way to capture types implicitly with the [[scala.reflect.api.TypeTags#TypeTag]]
- *  context bound. See [[scala.reflect.api.TypeTags the type tags page]] for details.
+ *  {{{
+ *    scala> typeOf[List[Int]]
+ *    res0: reflect.runtime.universe.Type = scala.List[Int]
+ *  }}}
  *
- *  Finally, types can be instantiated manually using factory methods such as `typeRef` or `polyType`.
- *  This is necessary only in cases when `typeOf` or `typeTag` cannot be applied because the type cannot be spelt out
- *  in a Scala snippet, usually when writing macros. Manual construction requires deep knowledge of Scala compiler internals
- *  and should be avoided if possible.
+ *  In this example, a [[scala.reflect.api.Types#TypeRef]] is returned, which corresponds to the type constructor `List`
+ *  applied to the type argument `Int`.
  *
- *  === Using types ===
+ *  ''Note:'' Method `typeOf` does not work for types with type parameters, such as `typeOf[List[A]]` where `A` is
+ *  a type parameter. In this case, use [[scala.reflect.api.TypeTags#weakTypeOf]] instead.
  *
- *  Common operations on types are querying them for inner declarations or type conformance tests.
+ *  For other ways to instantiate types, see the [[http://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html corresponding section of the Reflection Guide]].
  *
- *  Every type has `members` and `declarations` methods (along with their singular counterparts `member` and `declaration`),
- *  which provide the list of definitions associated with that type. For example, to look up the `map` method of `List`, one can
- *  write `typeOf[List[_]].member("map": TermName)`, getting a `MethodSymbol`
+ *  === Common Operations on Types ===
  *
- *  Types expose `<:<` and `weak_<:<` methods to test for subtype relationships. The latter is an extension of the former - it also works
- *  with numeric types (for example, `Int <:< Long` is false, but `Int weak_<:< Long` is true). Unlike the subtype tests implemented by
- *  type tags, tests provided by `Type`s are aware of all the intricacies of the Scala type system and work correctly even for involved types.
+ *  Types are typically used for type conformance tests or are queried for declarations of members or inner types.
  *
- *  The vanilla `==` method should not be used to compare types for equality. Instead, one should always use the `=:=` method.
- *  Operator `=:=` knows about type aliases, e.g., `typeOf[scala.List[_]] =:= typeOf[scala.collection.immutable.List[_]]`.
+ *   - '''Subtyping Relationships''' can be tested using `<:<` and `weak_<:<`.
+ *   - '''Type Equality''' can be checked with `=:=`. It's important to note that `==` should not be used to compare types for equality-- `==` can't check for type equality in the presence of type aliases, while `=:=` can.
  *
- *  === Exploring types ===
+ *  Types can be queried for members and declarations by using the `members` and `declarations` methods (along with
+ *  their singular counterparts `member` and `declaration`), which provide the list of definitions associated with that type.
+ *  For example, to look up the `map` method of `List`, one can do:
  *
  *  {{{
- *  scala> import scala.reflect.runtime.universe._
- *  import scala.reflect.runtime.universe._
- *
- *  scala> typeOf[List[_]].members.sorted take 5 foreach println
- *  constructor List
- *  method companion
- *  method ::
- *  method :::
- *  method reverse_:::
- *
- *  scala> def test[T: TypeTag](x: T) = s"I've been called for an x typed as \${typeOf[T]}"
- *  test: [T](x: T)(implicit evidence\$1: reflect.runtime.universe.TypeTag[T])String
- *
- *  scala> test(2)
- *  res0 @ 3fc80fae: String = I've been called for an x typed as Int
- *
- *  scala> test(List(2, "x"))
- *  res1 @ 10139edf: String = I've been called for an x typed as List[Any]
+ *     scala> typeOf[List[_]].member("map": TermName)
+ *     res1: reflect.runtime.universe.Symbol = method map
  *  }}}
  *
+ * For more information about `Type`s, see the [[http://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html Reflection Guide: Symbols, Trees, and Types]]
+ *
  *  @groupname TypeCreators Types - Creation
  *  @groupname TypeOps      Types - Operations
+ *  @group ReflectionAPI
  *
  *  @contentDiagram hideNodes "*Api"
  */
@@ -171,7 +154,7 @@ trait Types { self: Universe =>
      */
     def baseClasses: List[Symbol]
 
-    /** The least type instance of given class which is a supertype
+    /** The least type instance of given class which is a super-type
      *  of this type.  Example:
      *  {{{
      *    class D[T]
@@ -182,16 +165,32 @@ trait Types { self: Universe =>
     def baseType(clazz: Symbol): Type
 
     /** This type as seen from prefix `pre` and class `clazz`. This means:
-     *  Replace all thistypes of `clazz` or one of its subclasses
+     *  Replace all `ThisType`s of `clazz` or one of its subclasses
      *  by `pre` and instantiate all parameters by arguments of `pre`.
-     *  Proceed analogously for thistypes referring to outer classes.
+     *  Proceed analogously for `ThisType`s referring to outer classes.
      *
      *  Example:
      *  {{{
-     *    class D[T] { def m: T }
-     *    class C extends p.D[Int]
-     *    T.asSeenFrom(ThisType(C), D)  (where D is owner of m)
-     *      = Int
+     *    scala> import scala.reflect.runtime.universe._
+     *    import scala.reflect.runtime.universe._
+     *
+     *    scala> class D[T] { def m: T = ??? }
+     *    defined class D
+     *
+     *    scala> class C extends D[Int]
+     *    defined class C
+     *
+     *    scala> val D = typeOf[D[_]].typeSymbol.asClass
+     *    D: reflect.runtime.universe.ClassSymbol = class D
+     *
+     *    scala> val C = typeOf[C].typeSymbol.asClass
+     *    C: reflect.runtime.universe.ClassSymbol = class C
+     *
+     *    scala> val T = D.typeParams(0).asType.toType
+     *    T: reflect.runtime.universe.Type = T
+     *
+     *    scala> T.asSeenFrom(ThisType(C), D)
+     *    res0: reflect.runtime.universe.Type = scala.Int
      *  }}}
      */
     def asSeenFrom(pre: Type, clazz: Symbol): Type
@@ -279,7 +278,7 @@ trait Types { self: Universe =>
    */
   implicit val ThisTypeTag: ClassTag[ThisType]
 
-  /** The constructor/deconstructor for `ThisType` instances.
+  /** The constructor/extractor for `ThisType` instances.
    *  @group Extractors
    */
   val ThisType: ThisTypeExtractor
@@ -323,7 +322,7 @@ trait Types { self: Universe =>
    */
   implicit val SingleTypeTag: ClassTag[SingleType]
 
-  /** The constructor/deconstructor for `SingleType` instances.
+  /** The constructor/extractor for `SingleType` instances.
    *  @group Extractors
    */
   val SingleType: SingleTypeExtractor
@@ -368,7 +367,7 @@ trait Types { self: Universe =>
    */
   implicit val SuperTypeTag: ClassTag[SuperType]
 
-  /** The constructor/deconstructor for `SuperType` instances.
+  /** The constructor/extractor for `SuperType` instances.
    *  @group Extractors
    */
   val SuperType: SuperTypeExtractor
@@ -413,7 +412,7 @@ trait Types { self: Universe =>
    */
   implicit val ConstantTypeTag: ClassTag[ConstantType]
 
-  /** The constructor/deconstructor for `ConstantType` instances.
+  /** The constructor/extractor for `ConstantType` instances.
    *  @group Extractors
    */
   val ConstantType: ConstantTypeExtractor
@@ -457,7 +456,7 @@ trait Types { self: Universe =>
    */
   implicit val TypeRefTag: ClassTag[TypeRef]
 
-  /** The constructor/deconstructor for `TypeRef` instances.
+  /** The constructor/extractor for `TypeRef` instances.
    *  @group Extractors
    */
   val TypeRef: TypeRefExtractor
@@ -522,7 +521,7 @@ trait Types { self: Universe =>
    */
   implicit val RefinedTypeTag: ClassTag[RefinedType]
 
-  /** The constructor/deconstructor for `RefinedType` instances.
+  /** The constructor/extractor for `RefinedType` instances.
    *  @group Extractors
    */
   val RefinedType: RefinedTypeExtractor
@@ -574,7 +573,7 @@ trait Types { self: Universe =>
    */
   implicit val ClassInfoTypeTag: ClassTag[ClassInfoType]
 
-  /** The constructor/deconstructor for `ClassInfoType` instances.
+  /** The constructor/extractor for `ClassInfoType` instances.
    *  @group Extractors
    */
   val ClassInfoType: ClassInfoTypeExtractor
@@ -617,7 +616,7 @@ trait Types { self: Universe =>
    */
   implicit val MethodTypeTag: ClassTag[MethodType]
 
-  /** The constructor/deconstructor for `MethodType` instances.
+  /** The constructor/extractor for `MethodType` instances.
    *  @group Extractors
    */
   val MethodType: MethodTypeExtractor
@@ -667,7 +666,7 @@ trait Types { self: Universe =>
    */
   implicit val NullaryMethodTypeTag: ClassTag[NullaryMethodType]
 
-  /** The constructor/deconstructor for `NullaryMethodType` instances.
+  /** The constructor/extractor for `NullaryMethodType` instances.
    *  @group Extractors
    */
   val NullaryMethodType: NullaryMethodTypeExtractor
@@ -703,7 +702,7 @@ trait Types { self: Universe =>
    */
   implicit val PolyTypeTag: ClassTag[PolyType]
 
-  /** The constructor/deconstructor for `PolyType` instances.
+  /** The constructor/extractor for `PolyType` instances.
    *  @group Extractors
    */
   val PolyType: PolyTypeExtractor
@@ -743,7 +742,7 @@ trait Types { self: Universe =>
    */
   implicit val ExistentialTypeTag: ClassTag[ExistentialType]
 
-  /** The constructor/deconstructor for `ExistentialType` instances.
+  /** The constructor/extractor for `ExistentialType` instances.
    *  @group Extractors
    */
   val ExistentialType: ExistentialTypeExtractor
@@ -784,7 +783,7 @@ trait Types { self: Universe =>
    */
   implicit val AnnotatedTypeTag: ClassTag[AnnotatedType]
 
-  /** The constructor/deconstructor for `AnnotatedType` instances.
+  /** The constructor/extractor for `AnnotatedType` instances.
    *  @group Extractors
    */
   val AnnotatedType: AnnotatedTypeExtractor
@@ -835,7 +834,7 @@ trait Types { self: Universe =>
    */
   implicit val TypeBoundsTag: ClassTag[TypeBounds]
 
-  /** The constructor/deconstructor for `TypeBounds` instances.
+  /** The constructor/extractor for `TypeBounds` instances.
    *  @group Extractors
    */
   val TypeBounds: TypeBoundsExtractor
@@ -892,7 +891,7 @@ trait Types { self: Universe =>
    */
   implicit val BoundedWildcardTypeTag: ClassTag[BoundedWildcardType]
 
-  /** The constructor/deconstructor for `BoundedWildcardType` instances.
+  /** The constructor/extractor for `BoundedWildcardType` instances.
    *  @group Extractors
    */
   val BoundedWildcardType: BoundedWildcardTypeExtractor
diff --git a/src/reflect/scala/reflect/api/Universe.scala b/src/reflect/scala/reflect/api/Universe.scala
index 7d1f5c9df1..4928b8bb38 100644
--- a/src/reflect/scala/reflect/api/Universe.scala
+++ b/src/reflect/scala/reflect/api/Universe.scala
@@ -2,10 +2,12 @@ package scala.reflect
 package api
 
 /**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
  * `Universe` provides a complete set of reflection operations which make it possible for one
  * to reflectively inspect Scala type relations, such as membership or subtyping.
  *
- * [[scala.reflect.api.Universe]] has two specialized sub-universes for different scenarios. 
+ * [[scala.reflect.api.Universe]] has two specialized sub-universes for different scenarios.
  * [[scala.reflect.api.JavaUniverse]] adds operations that link symbols and types to the underlying
  * classes and runtime values of a JVM instance-- this can be thought of as the `Universe` that
  * should be used for all typical use-cases of Scala reflection. [[scala.reflect.macros.Universe]]
@@ -24,16 +26,16 @@ package api
  *   - [[scala.reflect.api.FlagSets#FlagSet FlagSet]] represent sets of flags that apply to symbols and
  *     definition trees
  *   - [[scala.reflect.api.Constants#Constant Constants]] represent compile-time constants.
- * 
- * To obtain a `Universe` to use with Scala runtime reflection, simply make sure to use or import 
+ *
+ * To obtain a `Universe` to use with Scala runtime reflection, simply make sure to use or import
  * `scala.reflect.runtime.universe._`
  *   {{{
  *   scala> import scala.reflect.runtime.universe._
  *   import scala.reflect.runtime.universe._
- *   
+ *
  *   scala> typeOf[List[Int]]
  *   res0: reflect.runtime.universe.Type = scala.List[Int]
- *  
+ *
  *   scala> typeOf[Either[String, Int]]
  *   res1: reflect.runtime.universe.Type = scala.Either[String,Int]
  *   }}}
@@ -50,6 +52,7 @@ package api
  * For more information about `Universe`s, see the [[http://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html Reflection Guide: Universes]]
  *
  *  @groupprio Universe -1
+ *  @group ReflectionAPI
  *
  *  @contentDiagram hideNodes "*Api"
  */
diff --git a/src/reflect/scala/reflect/api/package.scala b/src/reflect/scala/reflect/api/package.scala
index bd9c72a839..dbda84dd0e 100644
--- a/src/reflect/scala/reflect/api/package.scala
+++ b/src/reflect/scala/reflect/api/package.scala
@@ -2,7 +2,10 @@ package scala.reflect
 
 import scala.reflect.api.{Universe => ApiUniverse}
 
-/** The Scala Reflection API (located in scala-reflect.jar).
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ * The Scala Reflection API (located in scala-reflect.jar).
  *
  * In Scala 2.10.0, the Scala Reflection API and its implementation have an "experimental" status.
  * This means that the API and the docs are not complete and can be changed in binary- and source-incompatible
@@ -16,9 +19,10 @@ import scala.reflect.api.{Universe => ApiUniverse}
  *  - [[scala.reflect.api.Mirrors]]
  *  - [[scala.reflect.api.Universe]]
  *
- *  For more information about Scala Reflection, see the 
+ *  For more information about Scala Reflection, see the
  * [[http://docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]]
  *
+ *  @groupname ReflectionAPI Scala Reflection API
  *  @groupprio API        9
  *  @groupprio Extractors 10
  *  @groupprio Tags       11
diff --git a/src/reflect/scala/reflect/internal/AnnotationCheckers.scala b/src/reflect/scala/reflect/internal/AnnotationCheckers.scala
index 05f80c8a0c..5318d3e540 100644
--- a/src/reflect/scala/reflect/internal/AnnotationCheckers.scala
+++ b/src/reflect/scala/reflect/internal/AnnotationCheckers.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2007-2012 LAMP/EPFL
+ * Copyright 2007-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/AnnotationInfos.scala b/src/reflect/scala/reflect/internal/AnnotationInfos.scala
index 46e4329b2e..7c12b5979d 100644
--- a/src/reflect/scala/reflect/internal/AnnotationInfos.scala
+++ b/src/reflect/scala/reflect/internal/AnnotationInfos.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2007-2012 LAMP/EPFL
+ * Copyright 2007-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/BaseTypeSeqs.scala b/src/reflect/scala/reflect/internal/BaseTypeSeqs.scala
index 539984c67f..d72f08674e 100644
--- a/src/reflect/scala/reflect/internal/BaseTypeSeqs.scala
+++ b/src/reflect/scala/reflect/internal/BaseTypeSeqs.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 package scala.reflect
diff --git a/src/reflect/scala/reflect/internal/Chars.scala b/src/reflect/scala/reflect/internal/Chars.scala
index b1ae105e56..2d07092862 100644
--- a/src/reflect/scala/reflect/internal/Chars.scala
+++ b/src/reflect/scala/reflect/internal/Chars.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2006-2012 LAMP/EPFL
+ * Copyright 2006-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 package scala.reflect
diff --git a/src/reflect/scala/reflect/internal/ClassfileConstants.scala b/src/reflect/scala/reflect/internal/ClassfileConstants.scala
index 62ed130232..7ccb661426 100644
--- a/src/reflect/scala/reflect/internal/ClassfileConstants.scala
+++ b/src/reflect/scala/reflect/internal/ClassfileConstants.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/Constants.scala b/src/reflect/scala/reflect/internal/Constants.scala
index 4e232e486b..28bc3e1dd0 100644
--- a/src/reflect/scala/reflect/internal/Constants.scala
+++ b/src/reflect/scala/reflect/internal/Constants.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/Definitions.scala b/src/reflect/scala/reflect/internal/Definitions.scala
index 2bc9f02758..e24971a309 100644
--- a/src/reflect/scala/reflect/internal/Definitions.scala
+++ b/src/reflect/scala/reflect/internal/Definitions.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/ExistentialsAndSkolems.scala b/src/reflect/scala/reflect/internal/ExistentialsAndSkolems.scala
index 833ab81b9f..59c027868e 100644
--- a/src/reflect/scala/reflect/internal/ExistentialsAndSkolems.scala
+++ b/src/reflect/scala/reflect/internal/ExistentialsAndSkolems.scala
@@ -1,5 +1,5 @@
 /* NSC -- new scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/FatalError.scala b/src/reflect/scala/reflect/internal/FatalError.scala
index 428803994b..a084fc24f3 100644
--- a/src/reflect/scala/reflect/internal/FatalError.scala
+++ b/src/reflect/scala/reflect/internal/FatalError.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 package scala.reflect.internal
diff --git a/src/reflect/scala/reflect/internal/Flags.scala b/src/reflect/scala/reflect/internal/Flags.scala
index bb454b1df7..30dd9c3e49 100644
--- a/src/reflect/scala/reflect/internal/Flags.scala
+++ b/src/reflect/scala/reflect/internal/Flags.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/InfoTransformers.scala b/src/reflect/scala/reflect/internal/InfoTransformers.scala
index e25ebc0076..82904b0b68 100644
--- a/src/reflect/scala/reflect/internal/InfoTransformers.scala
+++ b/src/reflect/scala/reflect/internal/InfoTransformers.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/Kinds.scala b/src/reflect/scala/reflect/internal/Kinds.scala
index eb94f0e11c..08686832ef 100644
--- a/src/reflect/scala/reflect/internal/Kinds.scala
+++ b/src/reflect/scala/reflect/internal/Kinds.scala
@@ -1,5 +1,5 @@
 /* NSC -- new scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/Mirrors.scala b/src/reflect/scala/reflect/internal/Mirrors.scala
index 019cf7f908..0beb8e368f 100644
--- a/src/reflect/scala/reflect/internal/Mirrors.scala
+++ b/src/reflect/scala/reflect/internal/Mirrors.scala
@@ -1,6 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/MissingRequirementError.scala b/src/reflect/scala/reflect/internal/MissingRequirementError.scala
index 5ede51d5f3..48203caa83 100644
--- a/src/reflect/scala/reflect/internal/MissingRequirementError.scala
+++ b/src/reflect/scala/reflect/internal/MissingRequirementError.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/Names.scala b/src/reflect/scala/reflect/internal/Names.scala
index 0114fb037c..c78ba72dfb 100644
--- a/src/reflect/scala/reflect/internal/Names.scala
+++ b/src/reflect/scala/reflect/internal/Names.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/Phase.scala b/src/reflect/scala/reflect/internal/Phase.scala
index ac30d49b8c..c0f4232724 100644
--- a/src/reflect/scala/reflect/internal/Phase.scala
+++ b/src/reflect/scala/reflect/internal/Phase.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/Printers.scala b/src/reflect/scala/reflect/internal/Printers.scala
index fd5a7cf88b..e513ccb32c 100644
--- a/src/reflect/scala/reflect/internal/Printers.scala
+++ b/src/reflect/scala/reflect/internal/Printers.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/Scopes.scala b/src/reflect/scala/reflect/internal/Scopes.scala
index 89332d0ae5..ab3b9b7ed7 100644
--- a/src/reflect/scala/reflect/internal/Scopes.scala
+++ b/src/reflect/scala/reflect/internal/Scopes.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/StdNames.scala b/src/reflect/scala/reflect/internal/StdNames.scala
index eacbf6a0cc..5e7f5777b2 100644
--- a/src/reflect/scala/reflect/internal/StdNames.scala
+++ b/src/reflect/scala/reflect/internal/StdNames.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/SymbolTable.scala b/src/reflect/scala/reflect/internal/SymbolTable.scala
index 2424e75949..d077a975a8 100644
--- a/src/reflect/scala/reflect/internal/SymbolTable.scala
+++ b/src/reflect/scala/reflect/internal/SymbolTable.scala
@@ -1,5 +1,5 @@
 /* NSC -- new scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/Symbols.scala b/src/reflect/scala/reflect/internal/Symbols.scala
index a6f156f947..7cb9a0e105 100644
--- a/src/reflect/scala/reflect/internal/Symbols.scala
+++ b/src/reflect/scala/reflect/internal/Symbols.scala
@@ -1,5 +1,5 @@
  /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
@@ -3269,6 +3269,14 @@ trait Symbols extends api.Symbols { self: SymbolTable =>
    */
   def mapParamss[T](sym: Symbol)(f: Symbol => T): List[List[T]] = mmap(sym.info.paramss)(f)
 
+  /** Return closest enclosing method, unless shadowed by an enclosing class. */
+  // TODO Move back to ExplicitOuter when the other call site is removed.
+  // no use of closures here in the interest of speed.
+  final def closestEnclMethod(from: Symbol): Symbol =
+    if (from.isSourceMethod) from
+    else if (from.isClass) NoSymbol
+    else closestEnclMethod(from.owner)
+
   /** An exception for cyclic references of symbol definitions */
   case class CyclicReference(sym: Symbol, info: Type)
   extends TypeError("illegal cyclic reference involving " + sym) {
diff --git a/src/reflect/scala/reflect/internal/TreeInfo.scala b/src/reflect/scala/reflect/internal/TreeInfo.scala
index 68decc27f5..38e55a3c01 100644
--- a/src/reflect/scala/reflect/internal/TreeInfo.scala
+++ b/src/reflect/scala/reflect/internal/TreeInfo.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/Trees.scala b/src/reflect/scala/reflect/internal/Trees.scala
index d6b4f18855..74bde132cb 100644
--- a/src/reflect/scala/reflect/internal/Trees.scala
+++ b/src/reflect/scala/reflect/internal/Trees.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/TypeDebugging.scala b/src/reflect/scala/reflect/internal/TypeDebugging.scala
index a4d426171d..68b4fa69a1 100644
--- a/src/reflect/scala/reflect/internal/TypeDebugging.scala
+++ b/src/reflect/scala/reflect/internal/TypeDebugging.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Paul Phillips
  */
 
diff --git a/src/reflect/scala/reflect/internal/Types.scala b/src/reflect/scala/reflect/internal/Types.scala
index 403bf7d492..e8054fcdf5 100644
--- a/src/reflect/scala/reflect/internal/Types.scala
+++ b/src/reflect/scala/reflect/internal/Types.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/pickling/ByteCodecs.scala b/src/reflect/scala/reflect/internal/pickling/ByteCodecs.scala
index 4670bd4eef..367a3b8b19 100644
--- a/src/reflect/scala/reflect/internal/pickling/ByteCodecs.scala
+++ b/src/reflect/scala/reflect/internal/pickling/ByteCodecs.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2007-2011, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2007-2013, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
diff --git a/src/reflect/scala/reflect/internal/pickling/PickleBuffer.scala b/src/reflect/scala/reflect/internal/pickling/PickleBuffer.scala
index 5d3cb92dc0..6170fcbb90 100644
--- a/src/reflect/scala/reflect/internal/pickling/PickleBuffer.scala
+++ b/src/reflect/scala/reflect/internal/pickling/PickleBuffer.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/pickling/UnPickler.scala b/src/reflect/scala/reflect/internal/pickling/UnPickler.scala
index b158a1ac26..43b982a8a4 100644
--- a/src/reflect/scala/reflect/internal/pickling/UnPickler.scala
+++ b/src/reflect/scala/reflect/internal/pickling/UnPickler.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/settings/AbsSettings.scala b/src/reflect/scala/reflect/internal/settings/AbsSettings.scala
index 89281e9835..a6fb4187ca 100644
--- a/src/reflect/scala/reflect/internal/settings/AbsSettings.scala
+++ b/src/reflect/scala/reflect/internal/settings/AbsSettings.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Paul Phillips
  */
 
diff --git a/src/reflect/scala/reflect/internal/settings/MutableSettings.scala b/src/reflect/scala/reflect/internal/settings/MutableSettings.scala
index 459326e96f..81368df7a6 100644
--- a/src/reflect/scala/reflect/internal/settings/MutableSettings.scala
+++ b/src/reflect/scala/reflect/internal/settings/MutableSettings.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 // $Id$
diff --git a/src/reflect/scala/reflect/internal/transform/Erasure.scala b/src/reflect/scala/reflect/internal/transform/Erasure.scala
index 977398909f..52d1657dc3 100644
--- a/src/reflect/scala/reflect/internal/transform/Erasure.scala
+++ b/src/reflect/scala/reflect/internal/transform/Erasure.scala
@@ -214,6 +214,9 @@ trait Erasure {
         specialConstructorErasure(clazz, restpe)
       case ExistentialType(tparams, restpe) =>
         specialConstructorErasure(clazz, restpe)
+      case RefinedType(parents, decls) =>
+        specialConstructorErasure(
+          clazz, specialScalaErasure.mergeParents(parents))
       case mt @ MethodType(params, restpe) =>
         MethodType(
           cloneSymbolsAndModify(params, specialScalaErasure),
@@ -221,7 +224,16 @@ trait Erasure {
       case TypeRef(pre, `clazz`, args) =>
         typeRef(pre, clazz, List())
       case tp =>
-        assert(clazz == ArrayClass || tp.isError, s"unexpected constructor erasure $tp for $clazz")
+        if (!(clazz == ArrayClass || tp.isError))
+          // See SI-6556. It seems in some cases the result constructor
+          // type of an anonymous class is a different version of the class.
+          // This has nothing to do with value classes per se.
+          // We simply used a less discriminating transform before, that
+          // did not look at the cases in detail.
+          // It seems there is a deeper problem here, which needs
+          // following up to. But we will not risk regressions
+          // in 2.10 because of it.
+          log(s"!!! unexpected constructor erasure $tp for $clazz")
         specialScalaErasure(tp)
     }
   }
diff --git a/src/reflect/scala/reflect/internal/util/Collections.scala b/src/reflect/scala/reflect/internal/util/Collections.scala
index 201b4dfe0a..2ba15e0776 100644
--- a/src/reflect/scala/reflect/internal/util/Collections.scala
+++ b/src/reflect/scala/reflect/internal/util/Collections.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Paul Phillips
  */
 
diff --git a/src/reflect/scala/reflect/internal/util/HashSet.scala b/src/reflect/scala/reflect/internal/util/HashSet.scala
index 0d0f16372c..4135f3c469 100644
--- a/src/reflect/scala/reflect/internal/util/HashSet.scala
+++ b/src/reflect/scala/reflect/internal/util/HashSet.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/util/Origins.scala b/src/reflect/scala/reflect/internal/util/Origins.scala
index e7a0c5b8f6..3259a12163 100644
--- a/src/reflect/scala/reflect/internal/util/Origins.scala
+++ b/src/reflect/scala/reflect/internal/util/Origins.scala
@@ -1,5 +1,5 @@
 /* NSC -- new scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author Paul Phillips
  */
 
diff --git a/src/reflect/scala/reflect/internal/util/Position.scala b/src/reflect/scala/reflect/internal/util/Position.scala
index 5456d66584..0725e9775b 100644
--- a/src/reflect/scala/reflect/internal/util/Position.scala
+++ b/src/reflect/scala/reflect/internal/util/Position.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  *
  */
diff --git a/src/reflect/scala/reflect/internal/util/Set.scala b/src/reflect/scala/reflect/internal/util/Set.scala
index d708a09de7..36bdb8174a 100644
--- a/src/reflect/scala/reflect/internal/util/Set.scala
+++ b/src/reflect/scala/reflect/internal/util/Set.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 package scala.reflect.internal.util
diff --git a/src/reflect/scala/reflect/internal/util/SourceFile.scala b/src/reflect/scala/reflect/internal/util/SourceFile.scala
index 788c7532d1..bc2d0ee4db 100644
--- a/src/reflect/scala/reflect/internal/util/SourceFile.scala
+++ b/src/reflect/scala/reflect/internal/util/SourceFile.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/internal/util/StringOps.scala b/src/reflect/scala/reflect/internal/util/StringOps.scala
index 281ade8134..8f6c409e0b 100644
--- a/src/reflect/scala/reflect/internal/util/StringOps.scala
+++ b/src/reflect/scala/reflect/internal/util/StringOps.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2002-2011, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2002-2013, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
diff --git a/src/reflect/scala/reflect/io/AbstractFile.scala b/src/reflect/scala/reflect/io/AbstractFile.scala
index e32207c58c..15befb67f1 100644
--- a/src/reflect/scala/reflect/io/AbstractFile.scala
+++ b/src/reflect/scala/reflect/io/AbstractFile.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/io/Directory.scala b/src/reflect/scala/reflect/io/Directory.scala
index a24534137d..c040d1eac5 100644
--- a/src/reflect/scala/reflect/io/Directory.scala
+++ b/src/reflect/scala/reflect/io/Directory.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2013, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
diff --git a/src/reflect/scala/reflect/io/File.scala b/src/reflect/scala/reflect/io/File.scala
index 9e306371f7..736ba5d51e 100644
--- a/src/reflect/scala/reflect/io/File.scala
+++ b/src/reflect/scala/reflect/io/File.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2013, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
diff --git a/src/reflect/scala/reflect/io/FileOperationException.scala b/src/reflect/scala/reflect/io/FileOperationException.scala
index 6bce799cea..13a1322798 100644
--- a/src/reflect/scala/reflect/io/FileOperationException.scala
+++ b/src/reflect/scala/reflect/io/FileOperationException.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2013, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
diff --git a/src/reflect/scala/reflect/io/NoAbstractFile.scala b/src/reflect/scala/reflect/io/NoAbstractFile.scala
index d503328a37..8c88d3abf6 100644
--- a/src/reflect/scala/reflect/io/NoAbstractFile.scala
+++ b/src/reflect/scala/reflect/io/NoAbstractFile.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Paul Phillips
  */
 
diff --git a/src/reflect/scala/reflect/io/Path.scala b/src/reflect/scala/reflect/io/Path.scala
index 9a1ff395a3..36fdc04db4 100644
--- a/src/reflect/scala/reflect/io/Path.scala
+++ b/src/reflect/scala/reflect/io/Path.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author Paul Phillips
  */
 
diff --git a/src/reflect/scala/reflect/io/PlainFile.scala b/src/reflect/scala/reflect/io/PlainFile.scala
index 14cb09317c..82b0568657 100644
--- a/src/reflect/scala/reflect/io/PlainFile.scala
+++ b/src/reflect/scala/reflect/io/PlainFile.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/io/Streamable.scala b/src/reflect/scala/reflect/io/Streamable.scala
index a083890e09..61ec8a4c23 100644
--- a/src/reflect/scala/reflect/io/Streamable.scala
+++ b/src/reflect/scala/reflect/io/Streamable.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author Paul Phillips
  */
 
diff --git a/src/reflect/scala/reflect/io/VirtualDirectory.scala b/src/reflect/scala/reflect/io/VirtualDirectory.scala
index e71c5cbb6b..78713c2ae0 100644
--- a/src/reflect/scala/reflect/io/VirtualDirectory.scala
+++ b/src/reflect/scala/reflect/io/VirtualDirectory.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  */
 
 package scala.reflect
diff --git a/src/reflect/scala/reflect/io/VirtualFile.scala b/src/reflect/scala/reflect/io/VirtualFile.scala
index 4884561f4e..95f4429fad 100644
--- a/src/reflect/scala/reflect/io/VirtualFile.scala
+++ b/src/reflect/scala/reflect/io/VirtualFile.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Martin Odersky
  */
 
diff --git a/src/reflect/scala/reflect/io/ZipArchive.scala b/src/reflect/scala/reflect/io/ZipArchive.scala
index 2512c4d92f..3b57721e89 100644
--- a/src/reflect/scala/reflect/io/ZipArchive.scala
+++ b/src/reflect/scala/reflect/io/ZipArchive.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Paul Phillips
  */
 
diff --git a/src/reflect/scala/reflect/macros/Aliases.scala b/src/reflect/scala/reflect/macros/Aliases.scala
index 7f7ab66848..92d76f4370 100644
--- a/src/reflect/scala/reflect/macros/Aliases.scala
+++ b/src/reflect/scala/reflect/macros/Aliases.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that defines shorthands for the
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  A slice of [[scala.reflect.macros.Context the Scala macros context]] that defines shorthands for the
  *  most frequently used types and functions of the underlying compiler universe.
  */
 trait Aliases {
diff --git a/src/reflect/scala/reflect/macros/Attachments.scala b/src/reflect/scala/reflect/macros/Attachments.scala
index ba5ccf88f1..a77cebf415 100644
--- a/src/reflect/scala/reflect/macros/Attachments.scala
+++ b/src/reflect/scala/reflect/macros/Attachments.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** Attachments provide a way to associate custom metadata with symbols and trees.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  Attachments provide a way to associate custom metadata with symbols and trees.
  *
  *  Along with `symbol` and `tpe`, which represent core metadata of trees, each tree
  *  carries the `attachments` field that can store other metadata: compiler-defined (e.g. positions) or user-defined.
diff --git a/src/reflect/scala/reflect/macros/Context.scala b/src/reflect/scala/reflect/macros/Context.scala
index 1f6e97adbc..aa1c1db227 100644
--- a/src/reflect/scala/reflect/macros/Context.scala
+++ b/src/reflect/scala/reflect/macros/Context.scala
@@ -5,7 +5,10 @@ package macros
 // the most lightweight context should just expose the stuff from the SIP
 // the full context should include all traits from scala.reflect.macros (and probably reside in scala-compiler.jar)
 
-/** The Scala macros context.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  The Scala macros context.
  *
  *  See [[scala.reflect.macros.package the overview page]] for a description of how macros work. This documentation
  *  entry provides information on the API available to macro writers.
diff --git a/src/reflect/scala/reflect/macros/Enclosures.scala b/src/reflect/scala/reflect/macros/Enclosures.scala
index 41d6af94e3..c48656b366 100644
--- a/src/reflect/scala/reflect/macros/Enclosures.scala
+++ b/src/reflect/scala/reflect/macros/Enclosures.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that exposes
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  A slice of [[scala.reflect.macros.Context the Scala macros context]] that exposes
  *  enclosing trees (method, class, compilation unit and currently compiled application),
  *  the enclosing position of the macro expansion, as well as macros and implicits
  *  that are currently in-flight.
diff --git a/src/reflect/scala/reflect/macros/Evals.scala b/src/reflect/scala/reflect/macros/Evals.scala
index 6aab3d5b02..37680c219b 100644
--- a/src/reflect/scala/reflect/macros/Evals.scala
+++ b/src/reflect/scala/reflect/macros/Evals.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that provides
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  A slice of [[scala.reflect.macros.Context the Scala macros context]] that provides
  *  a facility to evaluate trees.
  */
 trait Evals {
diff --git a/src/reflect/scala/reflect/macros/ExprUtils.scala b/src/reflect/scala/reflect/macros/ExprUtils.scala
index a9acc61735..458cde9692 100644
--- a/src/reflect/scala/reflect/macros/ExprUtils.scala
+++ b/src/reflect/scala/reflect/macros/ExprUtils.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that defines shorthands for the
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ * A slice of [[scala.reflect.macros.Context the Scala macros context]] that defines shorthands for the
  *  most common `Expr`-creating functions.
  */
 trait ExprUtils {
diff --git a/src/reflect/scala/reflect/macros/FrontEnds.scala b/src/reflect/scala/reflect/macros/FrontEnds.scala
index 8c47202342..67b24088b5 100644
--- a/src/reflect/scala/reflect/macros/FrontEnds.scala
+++ b/src/reflect/scala/reflect/macros/FrontEnds.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  A slice of [[scala.reflect.macros.Context the Scala macros context]] that
  *  provides facilities to communicate with the compiler's front end
  *  (emit warnings, errors and other sorts of messages).
  */
diff --git a/src/reflect/scala/reflect/macros/Infrastructure.scala b/src/reflect/scala/reflect/macros/Infrastructure.scala
index 2f3b8e8d19..99706e84fe 100644
--- a/src/reflect/scala/reflect/macros/Infrastructure.scala
+++ b/src/reflect/scala/reflect/macros/Infrastructure.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  A slice of [[scala.reflect.macros.Context the Scala macros context]] that
  *  provides facilities to communicate with the compiler's infrastructure.
  */
 trait Infrastructure {
diff --git a/src/reflect/scala/reflect/macros/Names.scala b/src/reflect/scala/reflect/macros/Names.scala
index 20e750b225..8bbaa5f848 100644
--- a/src/reflect/scala/reflect/macros/Names.scala
+++ b/src/reflect/scala/reflect/macros/Names.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  A slice of [[scala.reflect.macros.Context the Scala macros context]] that
  *  provides functions that generate unique names.
  */
 trait Names {
diff --git a/src/reflect/scala/reflect/macros/Parsers.scala b/src/reflect/scala/reflect/macros/Parsers.scala
index bf73c36b1b..93a763792c 100644
--- a/src/reflect/scala/reflect/macros/Parsers.scala
+++ b/src/reflect/scala/reflect/macros/Parsers.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  A slice of [[scala.reflect.macros.Context the Scala macros context]] that
  *  exposes functions to parse strings with Scala code into trees.
  */
 trait Parsers {
diff --git a/src/reflect/scala/reflect/macros/Reifiers.scala b/src/reflect/scala/reflect/macros/Reifiers.scala
index d7ee30c7d9..3db7b9af02 100644
--- a/src/reflect/scala/reflect/macros/Reifiers.scala
+++ b/src/reflect/scala/reflect/macros/Reifiers.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ * A slice of [[scala.reflect.macros.Context the Scala macros context]] that
  *  exposes functions to save reflection artifacts for runtime.
  */
 trait Reifiers {
diff --git a/src/reflect/scala/reflect/macros/TreeBuilder.scala b/src/reflect/scala/reflect/macros/TreeBuilder.scala
index 727387c5af..204dc40858 100644
--- a/src/reflect/scala/reflect/macros/TreeBuilder.scala
+++ b/src/reflect/scala/reflect/macros/TreeBuilder.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A helper available in [[scala.reflect.macros.Universe]] that defines shorthands for the
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  A helper available in [[scala.reflect.macros.Universe]] that defines shorthands for the
  *  most common tree-creating functions.
  */
 abstract class TreeBuilder {
@@ -50,25 +53,18 @@ abstract class TreeBuilder {
    */
   def mkMethodCall(receiver: Symbol, methodName: Name, targs: List[Type], args: List[Tree]): Tree
 
-  /** TODO how to refer to the main `mkMethodCall`? */
   def mkMethodCall(method: Symbol, targs: List[Type], args: List[Tree]): Tree
 
-  /** TODO how to refer to the main `mkMethodCall`? */
   def mkMethodCall(method: Symbol, args: List[Tree]): Tree
 
-  /** TODO how to refer to the main `mkMethodCall`? */
   def mkMethodCall(target: Tree, args: List[Tree]): Tree
 
-  /** TODO how to refer to the main `mkMethodCall`? */
   def mkMethodCall(receiver: Symbol, methodName: Name, args: List[Tree]): Tree
 
-  /** TODO how to refer to the main `mkMethodCall`? */
   def mkMethodCall(receiver: Tree, method: Symbol, targs: List[Type], args: List[Tree]): Tree
 
-  /** TODO how to refer to the main `mkMethodCall`? */
   def mkMethodCall(target: Tree, targs: List[Type], args: List[Tree]): Tree
 
-  /** TODO how to refer to the main `mkMethodCall`? */
   def mkNullaryCall(method: Symbol, targs: List[Type]): Tree
 
   /** A tree that refers to the runtime reflexive universe, ``scala.reflect.runtime.universe''. */
diff --git a/src/reflect/scala/reflect/macros/Typers.scala b/src/reflect/scala/reflect/macros/Typers.scala
index 016a08bd01..427e7854b2 100644
--- a/src/reflect/scala/reflect/macros/Typers.scala
+++ b/src/reflect/scala/reflect/macros/Typers.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  A slice of [[scala.reflect.macros.Context the Scala macros context]] that
  *  partially exposes the type checker to macro writers.
  */
 trait Typers {
diff --git a/src/reflect/scala/reflect/macros/Universe.scala b/src/reflect/scala/reflect/macros/Universe.scala
index 86bc37b4c9..4e76f7c408 100644
--- a/src/reflect/scala/reflect/macros/Universe.scala
+++ b/src/reflect/scala/reflect/macros/Universe.scala
@@ -1,7 +1,10 @@
 package scala.reflect
 package macros
 
-/** The refinement of [[scala.reflect.api.Universe]] for the use by macro writers.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  The refinement of [[scala.reflect.api.Universe]] for the use by macro writers.
  *
  *  This universe provides mutability for reflection artifacts (e.g. macros can change types of compiler trees,
  *  add annotation to symbols representing definitions, etc) and exposes some internal compiler functionality
diff --git a/src/reflect/scala/reflect/macros/package.scala b/src/reflect/scala/reflect/macros/package.scala
index 3a2f04bcf2..21d189bb25 100644
--- a/src/reflect/scala/reflect/macros/package.scala
+++ b/src/reflect/scala/reflect/macros/package.scala
@@ -1,6 +1,9 @@
 package scala.reflect
 
-/** The base package for Scala macros.
+/**
+ * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
+ *
+ *  The base package for Scala macros.
  *
  *  Macros are functions that are called by the compiler during compilation.
  *  Within these functions the programmer has access to compiler APIs exposed in [[scala.reflect.macros.Context]].
diff --git a/src/reflect/scala/reflect/runtime/ReflectionUtils.scala b/src/reflect/scala/reflect/runtime/ReflectionUtils.scala
index 73425bae55..7b093e0e80 100644
--- a/src/reflect/scala/reflect/runtime/ReflectionUtils.scala
+++ b/src/reflect/scala/reflect/runtime/ReflectionUtils.scala
@@ -1,5 +1,5 @@
 /* NSC -- new Scala compiler
- * Copyright 2005-2012 LAMP/EPFL
+ * Copyright 2005-2013 LAMP/EPFL
  * @author  Paul Phillips
  */