Merge pull request scala#1335 from cvogt/topic/reflection-scaladoc

improved reflection documentation

Author: xeno-by

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 type members are
+ *  replaced by the concrete types if ClassTags are available for them.
+ *  
+ *  Besides accessing the erasure, a ClassTag knows how to 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,102 @@ 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.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
+ 
+  /** 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, scalaArgs, javaArgs)`.
+   *  Here, `atp` is the annotation type, `scalaArgs` the arguments, and `javaArgs` the annotation's key-value 
+   *  pairs.
+   *
+   *  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 `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 {
     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 annotation 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,42 @@
 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 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 with the guarantee that no two elements have the same type. */
   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 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 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/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,71 @@ 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 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]
 
+    /**
+     * 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] itself does not have a method foo. 
+     */
     def splice: T
+    /**
+     * 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 */
@@ -27,6 +82,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 module 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