improved reflection documentation

Author: cvogt

src/library/scala/reflect/ClassTag.scala

@@ -5,17 +5,17 @@ import java.lang.{ Class => jClass }
 import scala.language.{implicitConversions, existentials}
 import scala.runtime.ScalaRunTime.{ arrayClass, arrayElementClass }
 
-/** A `ClassTag[T]` wraps a runtime class, which can be accessed via the `runtimeClass` method.
+/** A `ClassTag[T]` wraps a runtime class (the erasure) and can create array instances.
  *
- *  This is useful in itself, but also enables very important use case.
- *  Having this knowledge ClassTag can instantiate `Arrays`
- *  in those cases where the element type is unknown at compile time.
+ *  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
+ *  replaced by the concrete types if ClassTags are available for them.
+ *  
+ *  Besides accessing the erasure, a ClassTag knows how instantiate single- and multi-
+ *  dimensional `Arrays` where the element type is unknown at compile time.
  *
- *  If an implicit value of type u.ClassTag[T] is required, the compiler will make one up on demand.
- *  The implicitly created value contains in its `runtimeClass` field the runtime class that is the result of erasing type T.
- *  In that value, any occurrences of type parameters or abstract types U which come themselves with a ClassTag
- *  are represented by the type referenced by that tag.
- *  If the type T contains unresolved references to type parameters or abstract types, a static error results.
+ * [[scala.reflect.ClassTag]] corresponds to a previous concept of [[scala.reflect.ClassManifest]].
  *
  * @see [[scala.reflect.base.TypeTags]]
  */
@@ -76,7 +76,7 @@ trait ClassTag[T] extends ClassManifestDeprecatedApis[T] with Equals with Serial
       if (conforms) Some(x.asInstanceOf[T]) else None
     }
 
-  /** case class accessories */
+  // case class accessories
   override def canEqual(x: Any) = x.isInstanceOf[ClassTag[_]]
   override def equals(x: Any) = x.isInstanceOf[ClassTag[_]] && this.runtimeClass == x.asInstanceOf[ClassTag[_]].runtimeClass
   override def hashCode = scala.runtime.ScalaRunTime.hash(runtimeClass)
@@ -88,6 +88,9 @@ trait ClassTag[T] extends ClassManifestDeprecatedApis[T] with Equals with Serial
   }
 }
 
+/**
+ * Class tags corresponding to primitive types and constructor/extractor for ClassTags.
+ */
 object ClassTag {
   private val ObjectTYPE = classOf[java.lang.Object]
   private val NothingTYPE = classOf[scala.runtime.Nothing$]

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

@@ -3,42 +3,103 @@ package base
 
 import scala.collection.immutable.ListMap
 
+/**
+ * Defines the type hierarchy for annotations.
+ */
 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]].
+   *  Trait `ClassfileAnnotation` is automatically added to every Java annotation by the scalac classfile parser. 
+   */
   type Annotation >: Null <: AnyRef
+ 
+  /** A tag that preserves the identity of the `Annotation` abstract type from erasure.
+   *  Can be used for pattern matching, instance tests, serialization and likes.
+   */
   implicit val AnnotationTag: ClassTag[Annotation]
-  val Annotation: AnnotationExtractor
 
+  /** 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 
+   *  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`.
+   *
+   *  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 
+   *  `javaArgs`. 
+   */ 
   abstract class AnnotationExtractor {
     def apply(tpe: Type, scalaArgs: List[Tree], javaArgs: ListMap[Name, JavaArgument]): Annotation
     def unapply(ann: Annotation): Option[(Type, List[Tree], ListMap[Name, JavaArgument])]
   }
 
+  /** A Java annotation argument */
   type JavaArgument >: Null <: AnyRef
   implicit val JavaArgumentTag: ClassTag[JavaArgument]
 
+  /** A literal argument to a Java annotation as `"Use X instead"` in `@Deprecated("Use X instead")`*/
   type LiteralArgument >: Null <: AnyRef with JavaArgument
+
+  /** A tag that preserves the identity of the `LiteralArgument` abstract type from erasure.
+   *  Can be used for pattern matching, instance tests, serialization and likes.
+   */
   implicit val LiteralArgumentTag: ClassTag[LiteralArgument]
+
+  /** The constructor/deconstructor for `LiteralArgument` instances. */
   val LiteralArgument: LiteralArgumentExtractor
 
+  /** An extractor class to create and pattern match with syntax `LiteralArgument(value)`
+   *  where `value` is the constant argument.
+   */
   abstract class LiteralArgumentExtractor {
     def apply(value: Constant): LiteralArgument
     def unapply(arg: LiteralArgument): Option[Constant]
   }
 
+  /** An array argument to a Java annotation as in `@Target(value={TYPE,FIELD,METHOD,PARAMETER})`
+   */
   type ArrayArgument >: Null <: AnyRef with JavaArgument
+
+  /** A tag that preserves the identity of the `ArrayArgument` abstract type from erasure.
+   *  Can be used for pattern matching, instance tests, serialization and likes.
+   */
   implicit val ArrayArgumentTag: ClassTag[ArrayArgument]
+
+  /** The constructor/deconstructor for `ArrayArgument` instances. */
   val ArrayArgument: ArrayArgumentExtractor
 
+  /** An extractor class to create and pattern match with syntax `ArrayArgument(args)`
+   *  where `args` is the argument array.
+   */
   abstract class ArrayArgumentExtractor {
     def apply(args: Array[JavaArgument]): ArrayArgument
     def unapply(arg: ArrayArgument): Option[Array[JavaArgument]]
   }
 
+  /** A nested argument to a Java annotation as `@Nested` in `@Outer(@Nested)`.
+   */
   type NestedArgument >: Null <: AnyRef with JavaArgument
+
+  /** A tag that preserves the identity of the `NestedArgument` abstract type from erasure.
+   *  Can be used for pattern matching, instance tests, serialization and likes.
+   */
   implicit val NestedArgumentTag: ClassTag[NestedArgument]
+
+  /** The constructor/deconstructor for `NestedArgument` instances. */
   val NestedArgument: NestedArgumentExtractor
 
+  /** An extractor class to create and pattern match with syntax `NestedArgument(annotation)`
+   *  where `annotation` is the nested annotation.
+   */
   abstract class NestedArgumentExtractor {
     def apply(annotation: Annotation): NestedArgument
     def unapply(arg: NestedArgument): Option[Annotation]

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

@@ -1,35 +1,38 @@
 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 generalisation of Position. Typically it stores a Position of a tree, but this can be extended to 
+ *  encompass arbitrary payloads.
  *
- *  Attachments have to carry positions, because we don't want to introduce even a single additional field in Tree
+ *  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.
  */
 abstract class Attachments { self =>
 
+  /** The position type of this attachment */
   type Pos >: Null
 
-  /** Gets the underlying position */
+  /** The underlying position */
   def pos: Pos
 
-  /** Creates a copy of this attachment with its position updated */
+  /** Creates a copy of this attachment with the position replaced by `newPos` */
   def withPos(newPos: Pos): Attachments { type Pos = self.Pos }
 
-  /** Gets the underlying payload */
+  /** The underlying payload. */
   def all: Set[Any] = Set.empty
 
   private def matchesTag[T: ClassTag](datum: Any) =
     classTag[T].runtimeClass == datum.getClass
 
+  /** An underlying payload of the given class type `T`. */
   def get[T: ClassTag]: Option[T] =
     (all filter matchesTag[T]).headOption.asInstanceOf[Option[T]]
 
-  /** Creates a copy of this attachment with its payload updated */
+  /** Creates a copy of this attachment with a new payload added */
   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. */
   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/Base.scala

@@ -7,6 +7,9 @@ import scala.ref.WeakReference
 import scala.collection.mutable
 import scala.collection.immutable.ListMap
 
+/**
+ * This is an internal implementation class.
+ */
 class Base extends Universe { self =>
 
   private var nextId = 0

src/library/scala/reflect/base/BuildUtils.scala

@@ -1,6 +1,9 @@
 package scala.reflect
 package base
 
+/**
+ * This is an internal implementation class.
+ */
 trait BuildUtils { self: Universe =>
 
   val build: BuildBase

src/library/scala/reflect/base/Constants.scala

@@ -6,13 +6,29 @@
 package scala.reflect
 package base
 
+/**
+ * Defines the type hierachy for compile-time constants.
+ *
+ * @see [[scala.reflect]] for a description on how the class hierarchy is encoded here.
+ */
 trait Constants {
   self: Universe =>
 
+  /** The type of compile-time constants.
+   */
   type Constant >: Null <: AnyRef
+
+  /** A tag that preserves the identity of the `Constant` abstract type from erasure.
+   *  Can be used for pattern matching, instance tests, serialization and likes.
+   */
   implicit val ConstantTag: ClassTag[Constant]
+
+  /** The constructor/deconstructor for `Constant` instances. */
   val Constant: ConstantExtractor
 
+  /** An extractor class to create and pattern match with syntax `Constant(value)`
+   *  where `value` is the Scala value of the constant.
+   */
   abstract class ConstantExtractor {
     def apply(value: Any): Constant
     def unapply(arg: Constant): Option[Any]

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

@@ -8,16 +8,54 @@ package base
 
 trait Exprs { self: Universe =>
 
-  /** An expression tree tagged with its type */
+  /** Expr wraps an expression tree and tags it with its type. */
   trait Expr[+T] extends Equals with Serializable {
     val mirror: Mirror
+    /**
+     * Migrates the expression into another universe given its corresponding mirror.
+     */
     def in[U <: Universe with Singleton](otherMirror: MirrorOf[U]): U # Expr[T]
 
+    /**
+     * The Scala syntax tree representing the wrapped expression.
+     */
     def tree: Tree
+    
+    /**
+     * Representation of the type of the wrapped expression tree as found via type tags.
+     */
     def staticType: Type
+    /**
+     * Representation of the type of the wrapped expression tree as found in the tree.
+     */
     def actualType: Type
 
+    /**
+     * 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.
+     * 
+     * If you want to use an Expr in reification of some Scala code, you need to splice it in.
+     * For an expr of type `Expr[T]`, where `T` has a method `foo`, the following code
+     * {{{
+     *   reify{ expr.splice.foo }
+     * }}}
+     * uses splice to turn an expr of type Expr[T] into a value of type T in the context of `reify`.
+     * 
+     * It is equivalent to 
+     * {{{
+     *   Select( expr.tree, newTermName("foo") )
+     * }}}
+     * 
+     * The following example code however does not compile
+     * {{{
+     *   reify{ expr.foo }
+     * }}}
+     * because expr of type Expr[T] does not have a method foo. 
+     */
     def splice: T
+    // TODO: document this
     val value: T
 
     /** case class accessories */
@@ -27,6 +65,12 @@ trait Exprs { self: Universe =>
     override def toString = "Expr["+staticType+"]("+tree+")"
   }
 
+  /**
+   * Constructor/Extractor for Expr.
+   * 
+   * Can be useful, when having a tree and wanting to splice it in reify call,
+   * in which case the tree first needs to be wrapped in an expr.
+   */
   object Expr {
     def apply[T: WeakTypeTag](mirror: MirrorOf[self.type], treec: TreeCreator): Expr[T] = new ExprImpl[T](mirror.asInstanceOf[Mirror], treec)
     def unapply[T](expr: Expr[T]): Option[Tree] = Some(expr.tree)

src/library/scala/reflect/base/FlagSets.scala

@@ -3,7 +3,7 @@ package base
 
 trait FlagSets { self: Universe =>
 
-  /** An abstract type representing sets of flags that apply to definition trees and symbols */
+  /** An abstract type representing sets of flags (like private, final, etc.) that apply to definition trees and symbols */
   type FlagSet
 
   /** A tag that preserves the identity of the `FlagSet` abstract type from erasure.

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

@@ -1,14 +1,33 @@
 package scala.reflect
 package base
 
+/**
+ * The base interface for all mirrors.
+ *
+ * @tparam U the type of the universe this mirror belongs to. 
+ * 
+ * This is defined outside the reflection universe cake pattern implementation
+ * so that it can be referenced from outside. For example TypeCreator and TreeCreator
+ * reference MirrorOf 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.
+ *
+ * @see [[Mirrors]]
+ */
 abstract class MirrorOf[U <: base.Universe with Singleton] {
-  /** .. */
+  /** The universe this mirror belongs to. */
   val universe: U
 
-  /** .. */
+  /** The class symbol of the `_root_` package */
   def RootClass: U#ClassSymbol
+
+  /** The module symbol of the `_root_` package */
   def RootPackage: U#ModuleSymbol
+
+  /** The class symbol of the default (unnamed) package */
   def EmptyPackageClass: U#ClassSymbol
+
+  /** The module symbol of the default (unnamed) package */
   def EmptyPackage: U#ModuleSymbol
 
   /** The symbol corresponding to the globally accessible class with the

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

@@ -1,12 +1,23 @@
 package scala.reflect
 package base
 
+/**
+ * Defines a type hierarchy for mirrors.
+ *
+ * Every universe has one or more mirrors. A mirror defines a hierarchy of symbols starting with the root package `_root_` 
+ * and provides methods to locate and define classes and singleton objects in that hierarchy.
+ *
+ * On the JVM, there is a one to one correspondance between class loaders and mirrors.
+ */
 trait Mirrors {
   self: Universe =>
 
-  /** .. */
+  /** 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.
+   */
   val rootMirror: Mirror
 }