improved/fixed reflection docs based on comments

Author: cvogt

src/library/scala/reflect/ClassTag.scala

@@ -9,10 +9,10 @@ import scala.runtime.ScalaRunTime.{ arrayClass, arrayElementClass }
  *
  *  If an implicit value of type ClassTag[T] is requested, the compiler will create one.
  *  The runtime class (i.e. the erasure, a java.lang.Class on the JVM) of T can be accessed
- *  via the `runtimeClass` field. References to type parameters or abstract types are
+ *  via the `runtimeClass` field. References to type parameters or abstract type members are
  *  replaced by the concrete types if ClassTags are available for them.
  *  
- *  Besides accessing the erasure, a ClassTag knows how instantiate single- and multi-
+ *  Besides accessing the erasure, a ClassTag knows how to instantiate single- and multi-
  *  dimensional `Arrays` where the element type is unknown at compile time.
  *
  * [[scala.reflect.ClassTag]] corresponds to a previous concept of [[scala.reflect.ClassManifest]].

src/library/scala/reflect/base/Annotations.scala

@@ -10,8 +10,8 @@ trait Annotations { self: Universe =>
 
   /** Typed information about an annotation. It can be attached to either a symbol or an annotated type. 
    *
-   *  Annotations are either ''Scala annotations'', which conform to [[scala.annotation.Annotation]] or [[scala.annotation.StaticAnnotation]]
-   *  but not [[scala.annotation.ClassfileAnnotation]] or ''Java annotations'', which conform to [[scala.annotation.ClassfileAnnotation]].
+   *  Annotations are either ''Scala annotations'', which conform to [[scala.annotation.StaticAnnotation]]
+   *  or ''Java annotations'', which conform to [[scala.annotation.ClassfileAnnotation]].
    *  Trait `ClassfileAnnotation` is automatically added to every Java annotation by the scalac classfile parser. 
    */
   type Annotation >: Null <: AnyRef
@@ -24,17 +24,16 @@ trait Annotations { self: Universe =>
   /** The constructor/deconstructor for `Annotation` instances. */
    val Annotation: AnnotationExtractor
 
-  /** An extractor class to create and pattern match with syntax `Annotation(atp, args, javaArgs)`.
-   *  Here, `atp` is the annotation type, `args` the arguments, and `javaArgs` the annotation's key-value 
+  /** An extractor class to create and pattern match with syntax `Annotation(atp, scalaArgs, javaArgs)`.
+   *  Here, `atp` is the annotation type, `scalaArgs` the arguments, and `javaArgs` the annotation's key-value 
    *  pairs.
    *
-   *  Annotations are written to the classfile as Java annotations if `atp` conforms to 
-   *  `ClassfileAnnotation`. Annotations are pickled, i.e., written to scala symtab attribute in the classfile, 
-   *  if `atp` inherits from `StaticAnnotation` but not `ClassfileAnnotation`.
+   *  Annotations are pickled, i.e. written to scala symtab attribute in the classfile.
+   *  Annotations are written to the classfile as Java annotations if `atp` conforms to `ClassfileAnnotation`. 
    *
-   *  For Scala annotations, arguments are stored in `args` and `javaArgs` is empty. Arguments in 
-   *  `args` are represented as typed trees. Note that these trees are not transformed by any phases 
-   *  following the type-checker. For Java annotations, `args` is empty and arguments are stored in 
+   *  For Scala annotations, arguments are stored in `scalaArgs` and `javaArgs` is empty. Arguments in 
+   *  `scalaArgs` are represented as typed trees. Note that these trees are not transformed by any phases 
+   *  following the type-checker. For Java annotations, `scalaArgs` is empty and arguments are stored in 
    *  `javaArgs`. 
    */ 
   abstract class AnnotationExtractor {
@@ -85,7 +84,7 @@ trait Annotations { self: Universe =>
     def unapply(arg: ArrayArgument): Option[Array[JavaArgument]]
   }
 
-  /** A nested argument to a Java annotation as `@Nested` in `@Outer(@Nested)`.
+  /** A nested annotation argument to a Java annotation as `@Nested` in `@Outer(@Nested)`.
    */
   type NestedArgument >: Null <: AnyRef with JavaArgument
 

src/library/scala/reflect/base/Attachments.scala

@@ -1,8 +1,9 @@
 package scala.reflect
 package base
 
-/** Attachments is a generalisation of Position. Typically it stores a Position of a tree, but this can be extended to 
- *  encompass arbitrary payloads.
+/** Attachments is a generalization of Position. Typically it stores a Position of a tree, but this can be extended to 
+ *  encompass arbitrary payloads. Payloads are stored in type-indexed slots, which can be read with `get[T]` and written
+ *  with `update[T]` and `remove[T]`.
  *
  *  Attachments always carry positions because we don't want to introduce an additional field for attachments in `Tree`
  *  imposing an unnecessary memory tax because of something that will not be used in most cases.
@@ -18,7 +19,7 @@ abstract class Attachments { self =>
   /** Creates a copy of this attachment with the position replaced by `newPos` */
   def withPos(newPos: Pos): Attachments { type Pos = self.Pos }
 
-  /** The underlying payload. */
+  /** The underlying payload with the guarantee that no two elements have the same type. */
   def all: Set[Any] = Set.empty
 
   private def matchesTag[T: ClassTag](datum: Any) =
@@ -28,11 +29,14 @@ abstract class Attachments { self =>
   def get[T: ClassTag]: Option[T] =
     (all filter matchesTag[T]).headOption.asInstanceOf[Option[T]]
 
-  /** Creates a copy of this attachment with a new payload added */
+  /** Creates a copy of this attachment with the payload slot of T added/updated with the provided value.
+   * 
+   * Replaces an existing payload of the same type, if exists.
+   */
   def update[T: ClassTag](attachment: T): Attachments { type Pos = self.Pos } =
     new NonemptyAttachments(this.pos, remove[T].all + attachment)
 
-  /** Creates a copy of this attachment with all payloads of the given class type `T` removed. */
+  /** Creates a copy of this attachment with the payload of the given class type `T` removed. */
   def remove[T: ClassTag]: Attachments { type Pos = self.Pos } = {
     val newAll = all filterNot matchesTag[T]
     if (newAll.isEmpty) pos.asInstanceOf[Attachments { type Pos = self.Pos }]

src/library/scala/reflect/base/Exprs.scala

@@ -12,7 +12,10 @@ trait Exprs { self: Universe =>
   trait Expr[+T] extends Equals with Serializable {
     val mirror: Mirror
     /**
-     * Migrates the expression into another universe given its corresponding mirror.
+     * Migrates the expression into another mirror, jumping into a different universe if necessary.
+     * 
+     * This means that all symbolic references to classes/objects/packages in the expression
+     * will be re-resolved within the new mirror (typically using that mirror's classloader).
      */
     def in[U <: Universe with Singleton](otherMirror: MirrorOf[U]): U # Expr[T]
 
@@ -32,6 +35,7 @@ trait Exprs { self: Universe =>
 
     /**
      * A dummy method to mark expression splicing in reification.
+     * 
      * It should only be used within a `reify` call, which eliminates the `splice` call and embeds
      * the wrapped tree into the reified surrounding expression. 
      * If used alone `splice` throws an exception when called at runtime.
@@ -52,10 +56,23 @@ trait Exprs { self: Universe =>
      * {{{
      *   reify{ expr.foo }
      * }}}
-     * because expr of type Expr[T] does not have a method foo. 
+     * because expr of type Expr[T] itself does not have a method foo. 
      */
     def splice: T
-    // TODO: document this
+    /**
+     * A dummy value to denote cross-stage path-dependent type dependencies.
+     * 
+     * For example for the following macro definition:
+     * {{{
+     * class X { type T }
+     * object Macros { def foo(x: X): x.T = macro Impls.foo_impl }
+     * }}}
+     * 
+     * The corresponding macro implementation should have the following signature (note how the return type denotes path-dependency on x):
+     * {{{
+     * object Impls { def foo_impl(c: Context)(x: c.Expr[X]): c.Expr[x.value.T] = ... }
+     * }}}
+     */
     val value: T
 
     /** case class accessories */

src/library/scala/reflect/base/MirrorOf.scala

@@ -24,7 +24,7 @@ abstract class MirrorOf[U <: base.Universe with Singleton] {
   /** The module symbol of the `_root_` package */
   def RootPackage: U#ModuleSymbol
 
-  /** The class symbol of the default (unnamed) package */
+  /** The module class symbol of the default (unnamed) package */
   def EmptyPackageClass: U#ClassSymbol
 
   /** The module symbol of the default (unnamed) package */

src/library/scala/reflect/base/Mirrors.scala

@@ -15,9 +15,8 @@ trait Mirrors {
   /** The base type of all mirrors of this universe */
   type Mirror >: Null <: MirrorOf[self.type]
 
-  /** The roor mirror of this universe. This mirror contains standard Scala classes and types such as `Any`, `AnyRef`, `AnyVal`, 
-   *  `Nothing`, `Null`, and all classes loaded from scala-library. The root package of this mirror contains the root 
-   *  packages of all other mirrors of this universe as members.
+  /** The root mirror of this universe. This mirror contains standard Scala classes and types such as `Any`, `AnyRef`, `AnyVal`, 
+   *  `Nothing`, `Null`, and all classes loaded from scala-library, which are shared across all mirrors within the enclosing universe.
    */
   val rootMirror: Mirror
 }

src/library/scala/reflect/base/Names.scala

@@ -37,10 +37,10 @@ trait Names {
 
   /** The base API that all names support */
   abstract class NameBase {
-    /** Checks weather the name is a a term name */
+    /** Checks wether the name is a a term name */
     def isTermName: Boolean
 
-    /** Checks weather the name is a a type name */
+    /** Checks wether the name is a a type name */
     def isTypeName: Boolean
 
     /** Returns a term name that wraps the same string as `this` */
@@ -58,11 +58,11 @@ trait Names {
    */
   def newTypeName(s: String): TypeName
 
-  /** Wraps the empty string
+  /** Wraps the empty string. Can be used as the null object for term name.
    */
   def EmptyTermName: TermName = newTermName("")
 
-  /** Wraps the empty string
+  /** Wraps the empty string. Can be used as the null object for term name.
    */
   def EmptyTypeName: TypeName = EmptyTermName.toTypeName
 }

src/library/scala/reflect/base/StandardDefinitions.scala

@@ -20,7 +20,7 @@ trait StandardDefinitions {
     /** The class symbol of package `scala`. */
     def ScalaPackageClass: ClassSymbol
 
-    /** The module symbol of package `scala`. */
+    /** The module class symbol of package `scala`. */
     def ScalaPackage: ModuleSymbol
 
     // top types

src/library/scala/reflect/base/Symbols.scala

@@ -86,10 +86,10 @@ trait Symbols { self: Universe =>
      *  that directly contains the current symbol's definition.
      *  The `NoSymbol` symbol does not have an owner, and calling this method
      *  on one causes an internal error.
-     *  The owner of the Scala root class [[scala.reflect.api.mirror.RootClass]]
-     *  and the Scala root object [[scala.reflect.api.mirror.RootPackage]] is `NoSymbol`.
+     *  The owner of the Scala root class [[scala.reflect.base.MirrorOf.RootClass]]
+     *  and the Scala root object [[scala.reflect.base.MirrorOf.RootPackage]] is `NoSymbol`.
      *  Every other symbol has a chain of owners that ends in
-     *  [[scala.reflect.api.mirror.RootClass]].
+     *  [[scala.reflect.base.MirrorOf.RootClass]].
      */
     def owner: Symbol
 

src/library/scala/reflect/base/TreeCreator.scala

@@ -1,6 +1,26 @@
 package scala.reflect
 package base
 
+/** A mirror-aware factory for trees.
+ *
+ * In the reflection API, artifacts are specific to universes and
+ * symbolic references used in artifacts (e.g. `scala.Int`) are resolved by mirrors.
+ *
+ * Therefore to build a tree one needs to know a universe that the tree is going to be bound to
+ * and a mirror that is going to resolve symbolic references (e.g. to determine that `scala.Int`
+ * points to a core class `Int` from scala-library.jar).
+ *
+ * `TreeCreator` implements this notion by providing a standalone tree factory.
+ *
+ * This is immediately useful for reification. When the compiler reifies an expression,
+ * the end result needs to make sense in any mirror. That's because the compiler knows
+ * the universe it's reifying an expression into (specified by the target of the `reify` call),
+ * but it cannot know in advance the mirror to instantiate the result in (e.g. on JVM
+ * it doesn't know what classloader use to resolve symbolic names in the reifee).
+ *
+ * Due to a typechecker restriction (no eta-expansion for dependent method types),
+ * `TreeCreator` can't have a functional type, so it's implemented as class with an apply method.
+ */
 abstract class TreeCreator {
   def apply[U <: Universe with Singleton](m: MirrorOf[U]): U # Tree
 }

src/library/scala/reflect/base/Trees.scala

@@ -88,7 +88,7 @@ trait Trees { self: Universe =>
   /** The empty tree */
   val EmptyTree: Tree
 
-  /** A tree for a term.  Not all trees are TermTrees; use isTerm
+  /** A tree for a term.  Not all trees representing terms are TermTrees; use isTerm
    *  to reliably identify terms.
    */
   type TermTree >: Null <: AnyRef with Tree
@@ -98,7 +98,7 @@ trait Trees { self: Universe =>
    */
   implicit val TermTreeTag: ClassTag[TermTree]
 
-  /** A tree for a type. Not all trees are TypTrees; use isType
+  /** A tree for a type. Not all trees representing types are TypTrees; use isType
    *  to reliably identify types.
    */
   type TypTree >: Null <: AnyRef with Tree
@@ -250,7 +250,6 @@ trait Trees { self: Universe =>
    */
   implicit val ValOrDefDefTag: ClassTag[ValOrDefDef]
 
-  // FIXME: document how ValDef in self-types can be recognized. (Only private modifier is set there.)
   /** Broadly speaking, a value definition.  All these are encoded as ValDefs:
    *
    *   - immutable values, e.g. "val x"
@@ -513,7 +512,7 @@ trait Trees { self: Universe =>
 
   /** Case clause in a pattern match.
    *  (except for occurrences in switch statements).
-   *  Eliminated by compiler phases patmat/explicitouter.
+   *  Eliminated by compiler phases patmat (in the new pattern matcher of 2.10) or explicitouter (in the old pre-2.10 pattern matcher)
    */
   type CaseDef >: Null <: AnyRef with Tree
 
@@ -538,7 +537,10 @@ trait Trees { self: Universe =>
     def unapply(caseDef: CaseDef): Option[(Tree, Tree, Tree)]
   }
 
-  /** Alternatives of patterns, eliminated by compiler phases patmat/explicitouter, except for
+  /** Alternatives of patterns.
+   * 
+   * Eliminated by compiler phases Eliminated by compiler phases patmat (in the new pattern matcher of 2.10) or explicitouter (in the old pre-2.10 pattern matcher),
+   * except for
    *  occurrences in encoded Switch stmt (i.e. remaining Match(CaseDef(...)))
    */
   type Alternative >: Null <: TermTree
@@ -562,7 +564,8 @@ trait Trees { self: Universe =>
   }
 
   /** Repetition of pattern.
-   *  Eliminated by compiler phase patmat/explicitouter.
+   *  
+   *  Eliminated by compiler phases patmat (in the new pattern matcher of 2.10) or explicitouter (in the old pre-2.10 pattern matcher).
    */
   type Star >: Null <: TermTree
 
@@ -585,7 +588,8 @@ trait Trees { self: Universe =>
   }
 
   /** Bind a variable to a rhs pattern.
-   * Eliminated by compiler phase patmat/explicitouter.
+   * 
+   * Eliminated by compiler phases patmat (in the new pattern matcher of 2.10) or explicitouter (in the old pre-2.10 pattern matcher).
    *
    *  @param name
    *  @param body
@@ -610,12 +614,9 @@ trait Trees { self: Universe =>
     def unapply(bind: Bind): Option[(Name, Tree)]
   }
 
-  // TODO: evaluate if UnApply can be removed or at least moved out of reflection. 
   /** 
    * Used to represent `unapply` methods in pattern matching.
    *
-   * Introduced by typer, eliminated by patmat/explicitouter.
-   *
    *  For example:
    *  {{{
    *    2 match { case Foo(x) => x }
@@ -637,6 +638,8 @@ trait Trees { self: Universe =>
    *          EmptyTree,
    *          Ident(newTermName("x")))))
    *  }}}
+   *
+   * Introduced by typer. Eliminated by compiler phases patmat (in the new pattern matcher of 2.10) or explicitouter (in the old pre-2.10 pattern matcher).
    */
   type UnApply >: Null <: TermTree
 
@@ -705,7 +708,7 @@ trait Trees { self: Universe =>
    * 
    *    vparams => body
    *
-   *  The symbol of a Function is a synthetic TermSymbol having its name set to nme.ANON_FUN_NAME.
+   *  The symbol of a Function is a synthetic TermSymbol.
    *  It is the owner of the function's parameters.
    */
   abstract class FunctionExtractor {
@@ -786,10 +789,10 @@ trait Trees { self: Universe =>
     def unapply(if_ : If): Option[(Tree, Tree, Tree)]
   }
 
-  /** - Pattern matching expression  (before compiler phase explicitouter)
-   *  - Switch statements            (after compiler phase explicitouter)
+  /** - Pattern matching expression  (before compiler phase explicitouter before 2.10 / patmat from 2.10)
+   *  - Switch statements            (after compiler phase explicitouter before 2.10 / patmat from 2.10)
    *
-   *  After compiler phase explicitouter, cases will satisfy the following constraints:
+   *  After compiler phase explicitouter before 2.10 / patmat from 2.10, cases will satisfy the following constraints:
    *
    *  - all guards are `EmptyTree`,
    *  - all patterns will be either `Literal(Constant(x:Int))`
@@ -1002,9 +1005,8 @@ trait Trees { self: Universe =>
     def unapply(apply: Apply): Option[(Tree, List[Tree])]
   }
 
-  // TODO: what is it used for exactly? extend docs!
   /** Super reference, where `qual` is the corresponding `this` reference.
-   *  A super reference C.super[M] is represented as Super(This(C), M).
+   *  A super reference `C.super[M]` is represented as `Super(This(C), M)`.
    */
   type Super >: Null <: TermTree
 

src/library/scala/reflect/base/TypeCreator.scala

@@ -1,6 +1,26 @@
 package scala.reflect
 package base
 
+/** A mirror-aware factory for types.
+ *
+ * In the reflection API, artifacts are specific to universes and
+ * symbolic references used in artifacts (e.g. `scala.Int`) are resolved by mirrors.
+ *
+ * Therefore to build a type one needs to know a universe that the type is going to be bound to
+ * and a mirror that is going to resolve symbolic references (e.g. to determine that `scala.Int`
+ * points to a core class `Int` from scala-library.jar).
+ *
+ * `TypeCreator` implements this notion by providing a standalone type factory.
+ *
+ * This is immediately useful for type tags. When the compiler creates a type tag,
+ * the end result needs to make sense in any mirror. That's because the compiler knows
+ * the universe it's creating a type tag for (since `TypeTag` is path-dependent on a universe),
+ * but it cannot know in advance the mirror to instantiate the result in (e.g. on JVM
+ * it doesn't know what classloader use to resolve symbolic names in the type tag).
+ *
+ * Due to a typechecker restriction (no eta-expansion for dependent method types),
+ * `TypeCreator` can't have a functional type, so it's implemented as class with an apply method.
+ */
 abstract class TypeCreator {
   def apply[U <: Universe with Singleton](m: MirrorOf[U]): U # Type
 }