SI-6132 Revisited, cleaned-up, links fixed, spelling errors fixed, rewordings

26 files changed, 227 insertions, 194 deletions

diff --git a/src/reflect/scala/reflect/api/Annotations.scala b/src/reflect/scala/reflect/api/Annotations.scala
index ebfd57038c..09eaf7afb4 100644
--- a/src/reflect/scala/reflect/api/Annotations.scala
+++ b/src/reflect/scala/reflect/api/Annotations.scala
@@ -16,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
@@ -32,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 =>
 
@@ -48,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
@@ -105,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
@@ -140,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
@@ -175,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 89153706ed..4a8a2868cc 100644
--- a/src/reflect/scala/reflect/api/Constants.scala
+++ b/src/reflect/scala/reflect/api/Constants.scala
@@ -84,6 +84,7 @@ package api
  *  }}}
  *
  *  @contentDiagram hideNodes "*Api"
+ *  @group ReflectionAPI
  */
 trait Constants {
   self: Universe =>
@@ -188,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 739b9dca12..eeef94598c 100644
--- a/src/reflect/scala/reflect/api/Exprs.scala
+++ b/src/reflect/scala/reflect/api/Exprs.scala
@@ -27,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 =>
 
@@ -106,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 5cf7460dcd..4357aec9c9 100644
--- a/src/reflect/scala/reflect/api/FlagSets.scala
+++ b/src/reflect/scala/reflect/api/FlagSets.scala
@@ -21,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:
  * {{{
@@ -36,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
@@ -47,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 f68ff690cf..afc4f2f25d 100644
--- a/src/reflect/scala/reflect/api/Importers.scala
+++ b/src/reflect/scala/reflect/api/Importers.scala
@@ -5,16 +5,17 @@ package api
  * <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
@@ -55,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 43360c97a1..b678033e1a 100644
--- a/src/reflect/scala/reflect/api/JavaMirrors.scala
+++ b/src/reflect/scala/reflect/api/JavaMirrors.scala
@@ -15,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 8649f339e3..04d091ee9d 100644
--- a/src/reflect/scala/reflect/api/JavaUniverse.scala
+++ b/src/reflect/scala/reflect/api/JavaUniverse.scala
@@ -10,7 +10,9 @@ package api
  *  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 f600ee9caf..1223326d7c 100644
--- a/src/reflect/scala/reflect/api/Mirror.scala
+++ b/src/reflect/scala/reflect/api/Mirror.scala
@@ -10,10 +10,11 @@ package api
  * 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 c4573eaf99..d0d8a37584 100644
--- a/src/reflect/scala/reflect/api/Mirrors.scala
+++ b/src/reflect/scala/reflect/api/Mirrors.scala
@@ -17,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.
@@ -53,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.
@@ -62,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]],
@@ -205,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 3d124dafc4..7c12f180a8 100644
--- a/src/reflect/scala/reflect/api/Names.scala
+++ b/src/reflect/scala/reflect/api/Names.scala
@@ -4,21 +4,26 @@ package api
 /**
  * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
  *
- * This trait defines Names (a Scala reflection concept) and operations on them.
+ * This trait defines `Name`s in Scala Reflection, and operations on them.
  *
- *  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. 
+ *  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.
  *
- *  === Examples ===
+ *  To search for the `map` method (which is a term) declared in the `List` class, one can do:
  *
- *  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.
+ * {{{
+ *   scala> typeOf[List[_]].member(newTermName("map"))
+ *   res0: reflect.runtime.universe.Symbol = method map
+ * }}}
  *
- *  See the [[docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for more about Scala Reflection.
+ *  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 0dfd74f1b3..63c67627a3 100644
--- a/src/reflect/scala/reflect/api/Position.scala
+++ b/src/reflect/scala/reflect/api/Position.scala
@@ -9,14 +9,12 @@ 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.
  *
- * A position indicates the [[source source file]] and a [[point offset]]. A position may be
- * undefined, which means it's pointing to the [[Positions#NoPosition]] element.
- *
  * <b>Please note that this trait may be refactored in future versions of the Scala reflection API.</b>
  *
  * 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 {
 
diff --git a/src/reflect/scala/reflect/api/Positions.scala b/src/reflect/scala/reflect/api/Positions.scala
index 14cc0ab12c..87f00fdb88 100644
--- a/src/reflect/scala/reflect/api/Positions.scala
+++ b/src/reflect/scala/reflect/api/Positions.scala
@@ -9,6 +9,7 @@ package 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 b1e14f798f..85ddcc6523 100644
--- a/src/reflect/scala/reflect/api/Printers.scala
+++ b/src/reflect/scala/reflect/api/Printers.scala
@@ -33,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.
@@ -57,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
  * {{{
@@ -92,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._
@@ -119,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 c79ec06b45..7f9799393c 100644
--- a/src/reflect/scala/reflect/api/Scopes.scala
+++ b/src/reflect/scala/reflect/api/Scopes.scala
@@ -17,6 +17,8 @@ package api
  * 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 480a28b878..61097e3f69 100644
--- a/src/reflect/scala/reflect/api/StandardDefinitions.scala
+++ b/src/reflect/scala/reflect/api/StandardDefinitions.scala
@@ -13,6 +13,8 @@ package api
  * 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 0c1ceae187..e24bc91ced 100644
--- a/src/reflect/scala/reflect/api/StandardNames.scala
+++ b/src/reflect/scala/reflect/api/StandardNames.scala
@@ -22,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 d91481724f..b53c700701 100644
--- a/src/reflect/scala/reflect/api/Symbols.scala
+++ b/src/reflect/scala/reflect/api/Symbols.scala
@@ -9,20 +9,49 @@ package api
  *  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 5486c34517..5de811578e 100644
--- a/src/reflect/scala/reflect/api/TagInterop.scala
+++ b/src/reflect/scala/reflect/api/TagInterop.scala
@@ -5,6 +5,8 @@ package api
  * <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 87a0348c15..d34fb78b89 100644
--- a/src/reflect/scala/reflect/api/Trees.scala
+++ b/src/reflect/scala/reflect/api/Trees.scala
@@ -10,26 +10,39 @@ package api
  *
  * This trait defines the node types used in Scala abstract syntax trees (AST) and operations on them.
  *
- *  All tree node types are sub types of [[scala.reflect.api.Trees#Tree Tree]].
+ * 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
@@ -37,6 +50,7 @@ package api
  *  @groupprio Copying   1
  *
  *  @contentDiagram hideNodes "*Api"
+ *  @group ReflectionAPI
  */
 trait Trees { self: Universe =>
 
@@ -349,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
@@ -408,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
@@ -459,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
@@ -542,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
@@ -597,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
@@ -652,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
@@ -717,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
@@ -779,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
@@ -831,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
@@ -889,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
@@ -947,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
@@ -992,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
@@ -1045,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
@@ -1083,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
@@ -1124,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
@@ -1193,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
@@ -1235,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
@@ -1279,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
@@ -1321,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
@@ -1368,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
@@ -1425,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
@@ -1466,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
@@ -1504,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
@@ -1548,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
@@ -1584,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
@@ -1631,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
@@ -1697,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
@@ -1731,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
@@ -1774,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
@@ -1826,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
@@ -1867,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
@@ -1906,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
@@ -1951,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
@@ -2001,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
@@ -2040,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
@@ -2080,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
@@ -2117,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
@@ -2158,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
@@ -2194,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
@@ -2233,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
@@ -2276,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
@@ -2319,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
@@ -2912,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..083a495c30 100644
--- a/src/reflect/scala/reflect/api/TypeTags.scala
+++ b/src/reflect/scala/reflect/api/TypeTags.scala
@@ -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 ab165a13b7..f3201ae328 100644
--- a/src/reflect/scala/reflect/api/Types.scala
+++ b/src/reflect/scala/reflect/api/Types.scala
@@ -7,66 +7,46 @@ package api
  *  A trait that defines types and operations on them.
  *
  *  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.
+ *  (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.
  *
- *  === Instantiating types ===
+ *  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:
  *
- *  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.
- *
- *  `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"
  */
@@ -174,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]
@@ -185,15 +165,15 @@ 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)
+     *    T.asSeenFrom(ThisType(C), D)  // (where D is the owner of m)
      *      = Int
      *  }}}
      */
@@ -282,7 +262,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
@@ -326,7 +306,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
@@ -371,7 +351,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
@@ -416,7 +396,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
@@ -460,7 +440,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
@@ -525,7 +505,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
@@ -577,7 +557,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
@@ -620,7 +600,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
@@ -670,7 +650,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
@@ -706,7 +686,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
@@ -746,7 +726,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
@@ -787,7 +767,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
@@ -838,7 +818,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
@@ -895,7 +875,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 068ab94a4c..4928b8bb38 100644
--- a/src/reflect/scala/reflect/api/Universe.scala
+++ b/src/reflect/scala/reflect/api/Universe.scala
@@ -7,7 +7,7 @@ package api
  * `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]]
@@ -26,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]
  *   }}}
@@ -52,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 68466b9f09..dbda84dd0e 100644
--- a/src/reflect/scala/reflect/api/package.scala
+++ b/src/reflect/scala/reflect/api/package.scala
@@ -19,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/macros/TreeBuilder.scala b/src/reflect/scala/reflect/macros/TreeBuilder.scala
index 362b35686c..204dc40858 100644
--- a/src/reflect/scala/reflect/macros/TreeBuilder.scala
+++ b/src/reflect/scala/reflect/macros/TreeBuilder.scala
@@ -53,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''. */