Merge pull request scala#1492 from scalamacros/pullrequest/reflection-docs

Pullrequest/reflection docs

Author: jsuereth

src/compiler/scala/reflect/macros/runtime/Typers.scala

@@ -8,6 +8,9 @@ trait Typers {
 
   def openImplicits: List[(Type, Tree)] = callsiteTyper.context.openImplicits
 
+  /**
+   * @see [[scala.tools.reflect.Toolbox.typeCheck]]
+   */
   def typeCheck(tree: Tree, pt: Type = universe.WildcardType, silent: Boolean = false, withImplicitViewsDisabled: Boolean = false, withMacrosDisabled: Boolean = false): Tree = {
     macroLogVerbose("typechecking %s with expected type %s, implicit views = %s, macros = %s".format(tree, pt, !withImplicitViewsDisabled, !withMacrosDisabled))
     val context = callsiteTyper.context

src/library/scala/reflect/ClassTag.scala

@@ -5,19 +5,34 @@ import java.lang.{ Class => jClass }
 import scala.language.{implicitConversions, existentials}
 import scala.runtime.ScalaRunTime.{ arrayClass, arrayElementClass }
 
-/** A `ClassTag[T]` wraps a runtime class (the erasure) and can create array instances.
+/**
+ *
+ * A `ClassTag[T]` stores the erased class of a given type `T`, accessible via the `runtimeClass`
+ * field. This is particularly useful for instantiating `Array`s whose element types are unknown
+ * at compile time.
+ *
+ * `ClassTag`s are a weaker special case of [[scala.reflect.api.TypeTags#TypeTag]]s, in that they
+ * wrap only the runtime class of a given type, whereas a `TypeTag` contains all static type
+ * information. That is, `ClassTag`s are constructed from knowing only the top-level class of a
+ * type, without necessarily knowing all of its argument types. This runtime information is enough
+ * for runtime `Array` creation.
  *
- *  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.
+ * For example:
+ * {{{
+ *   scala> def mkArray[T : ClassTag](elems: T*) = Array[T](elems: _*)
+ *   mkArray: [T](elems: T*)(implicit evidence$1: scala.reflect.ClassTag[T])Array[T]
  *
- *  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> mkArray(42, 13)
+ *   res0: Array[Int] = Array(42, 13)
  *
- * [[scala.reflect.ClassTag]] corresponds to a previous concept of [[scala.reflect.ClassManifest]].
+ *   scala> mkArray("Japan","Brazil","Germany")
+ *   res1: Array[String] = Array(Japan, Brazil, Germany)
+ * }}}
+ * 
+ * See [[scala.reflect.api.TypeTags]] for more examples, or the
+ * [[http://docs.scala-lang.org/overviews/reflection/typetags-manifests.html Reflection Guide: TypeTags]]
+ * for more details.
  *
- * @see [[scala.reflect.api.TypeTags]]
  */
 @scala.annotation.implicitNotFound(msg = "No ClassTag available for ${T}")
 trait ClassTag[T] extends ClassManifestDeprecatedApis[T] with Equals with Serializable {
@@ -29,7 +44,7 @@ trait ClassTag[T] extends ClassManifestDeprecatedApis[T] with Equals with Serial
    */
   def runtimeClass: jClass[_]
 
-  /** Produces a `ClassTag` that knows how to build `Array[Array[T]]` */
+  /** Produces a `ClassTag` that knows how to instantiate an `Array[Array[T]]` */
   def wrap: ClassTag[Array[T]] = ClassTag[Array[T]](arrayClass(runtimeClass))
 
   /** Produces a new array with element type `T` and length `len` */

src/reflect/scala/reflect/api/Annotations.scala

@@ -3,122 +3,195 @@ package api
 
 import scala.collection.immutable.ListMap
 
-/**
- * Defines the type hierarchy for annotations.
+/** This trait provides annotation support for the reflection API.
+ *
+ *  The API distinguishes between two kinds of annotations:
+ *
+ *  <ul>
+ *  <li>''Java annotations'': annotations on definitions produced by the Java compiler, i.e., subtypes of [[java.lang.annotation.Annotation]]
+ *  attached to program definitions. When read by Scala reflection, the [[scala.annotation.ClassfileAnnotation]] trait
+ *  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 
+ *  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
+ *  both `scalaArgs` and `javaArgs`. For Scala or Java annotations extending [[scala.annotation.ClassfileAnnotation]] `scalaArgs` is empty
+ *  and arguments are stored in `javaArgs`. For all other 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. Arguments in `javaArgs` are repesented as a map from [[scala.reflect.api.Names#Name]] to
+ *  [[scala.reflect.api.Annotations#JavaArgument]]. Instances of `JavaArgument` represent different kinds of Java annotation arguments:
+ *    - literals (primitive and string constants),
+ *    - arrays and
+ *    - nested annotations.
+ *
+ *  @contentDiagram hideNodes "*Api"
  */
 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.
+  /** Information about an annotation.
+   *  @template
+   *  @group Annotations
    */
   type Annotation >: Null <: AnyRef with AnnotationApi
 
   /** A tag that preserves the identity of the `Annotation` abstract type from erasure.
    *  Can be used for pattern matching, instance tests, serialization and likes.
+   *  @group Tags
    */
   implicit val AnnotationTag: ClassTag[Annotation]
 
-  /** The constructor/deconstructor for `Annotation` instances. */
+   /** The constructor/deconstructor for `Annotation` instances.
+    *  @group Extractors
+    */
    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`.
-   */
+  /** An extractor class to create and pattern match with syntax `Annotation(tpe, scalaArgs, javaArgs)`.
+   *  Here, `tpe` is the annotation type, `scalaArgs` the payload of Scala annotations, and `javaArgs` the payload of Java annotations.
+    *  @group Extractors
+    */
   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])]
   }
 
+  /** The API of `Annotation` instances.
+   *  The main source of information about annotations is the [[scala.reflect.api.Annotations]] page.
+   *  @group API
+   */
   trait AnnotationApi {
+    /** The type of the annotation. */
     def tpe: Type
+
+    /** Payload of the Scala annotation: a list of abstract syntax trees that represent the argument.
+     *  Empty for Java annotations.
+     */
     def scalaArgs: List[Tree]
+
+    /** Payload of the Java annotation: a list of name-value pairs.
+     *  Empty for Scala annotations.
+     */
     def javaArgs: ListMap[Name, JavaArgument]
   }
 
-  /** A Java annotation argument */
+  /** A Java annotation argument
+   *  @template
+   *  @group Annotations
+   */
   type JavaArgument >: Null <: AnyRef
+
+  /** A tag that preserves the identity of the `JavaArgument` abstract type from erasure.
+   *  Can be used for pattern matching, instance tests, serialization and likes.
+   *  @group Tags
+   */
   implicit val JavaArgumentTag: ClassTag[JavaArgument]
 
-  /** A literal argument to a Java annotation as `"Use X instead"` in `@Deprecated("Use X instead")`*/
+  /** A literal argument to a Java annotation as `"Use X instead"` in `@Deprecated("Use X instead")`
+   *  @template
+   *  @group Annotations
+   */
   type LiteralArgument >: Null <: AnyRef with JavaArgument with LiteralArgumentApi
 
   /** A tag that preserves the identity of the `LiteralArgument` abstract type from erasure.
    *  Can be used for pattern matching, instance tests, serialization and likes.
+   *  @group Tags
    */
   implicit val LiteralArgumentTag: ClassTag[LiteralArgument]
 
-  /** The constructor/deconstructor for `LiteralArgument` instances. */
+  /** The constructor/deconstructor for `LiteralArgument` instances.
+   *  @group Extractors
+   */
   val LiteralArgument: LiteralArgumentExtractor
 
   /** An extractor class to create and pattern match with syntax `LiteralArgument(value)`
    *  where `value` is the constant argument.
+   *  @group Extractors
    */
   abstract class LiteralArgumentExtractor {
     def apply(value: Constant): LiteralArgument
     def unapply(arg: LiteralArgument): Option[Constant]
   }
 
+  /** The API of `LiteralArgument` instances.
+   *  The main source of information about annotations is the [[scala.reflect.api.Annotations]] page.
+   *  @group API
+   */
   trait LiteralArgumentApi {
+    /** The underlying compile-time constant value. */
     def value: Constant
   }
 
   /** An array argument to a Java annotation as in `@Target(value={TYPE,FIELD,METHOD,PARAMETER})`
+   *  @template
+   *  @group Annotations
    */
   type ArrayArgument >: Null <: AnyRef with JavaArgument with ArrayArgumentApi
 
   /** A tag that preserves the identity of the `ArrayArgument` abstract type from erasure.
    *  Can be used for pattern matching, instance tests, serialization and likes.
+   *  @group Tags
    */
   implicit val ArrayArgumentTag: ClassTag[ArrayArgument]
 
-  /** The constructor/deconstructor for `ArrayArgument` instances. */
+  /** The constructor/deconstructor for `ArrayArgument` instances.
+   *  @group Extractors
+   */
   val ArrayArgument: ArrayArgumentExtractor
 
   /** An extractor class to create and pattern match with syntax `ArrayArgument(args)`
    *  where `args` is the argument array.
+   *  @group Extractors
    */
   abstract class ArrayArgumentExtractor {
     def apply(args: Array[JavaArgument]): ArrayArgument
     def unapply(arg: ArrayArgument): Option[Array[JavaArgument]]
   }
 
+  /** API of `ArrayArgument` instances.
+   *  The main source of information about annotations is the [[scala.reflect.api.Annotations]] page.
+   *  @group API
+   */
   trait ArrayArgumentApi {
+    /** The underlying array of Java annotation arguments. */
     def args: Array[JavaArgument]
   }
 
   /** A nested annotation argument to a Java annotation as `@Nested` in `@Outer(@Nested)`.
+   *  @template
+   *  @group Annotations
    */
   type NestedArgument >: Null <: AnyRef with JavaArgument with NestedArgumentApi
 
   /** A tag that preserves the identity of the `NestedArgument` abstract type from erasure.
    *  Can be used for pattern matching, instance tests, serialization and likes.
+   *  @group Tags
    */
   implicit val NestedArgumentTag: ClassTag[NestedArgument]
 
-  /** The constructor/deconstructor for `NestedArgument` instances. */
+  /** The constructor/deconstructor for `NestedArgument` instances.
+   *  @group Extractors
+   */
   val NestedArgument: NestedArgumentExtractor
 
   /** An extractor class to create and pattern match with syntax `NestedArgument(annotation)`
    *  where `annotation` is the nested annotation.
+   *  @group Extractors
    */
   abstract class NestedArgumentExtractor {
     def apply(annotation: Annotation): NestedArgument
     def unapply(arg: NestedArgument): Option[Annotation]
   }
 
+  /** API of `NestedArgument` instances.
+   *  The main source of information about annotations is the [[scala.reflect.api.Annotations]] page.
+   *  @group API
+   */
   trait NestedArgumentApi {
+    /** The underlying nested annotation. */
     def annotation: Annotation
   }
 }

src/reflect/scala/reflect/api/BuildUtils.scala

@@ -3,15 +3,18 @@ package api
 
 /**
  * This is an internal implementation class.
+ * @groupname TreeBuilders Tree Building
  */
 private[reflect] trait BuildUtils { self: Universe =>
 
+  /** @group TreeBuilders */
   val build: BuildApi
 
   // this API abstracts away the functionality necessary for reification
   // it's too gimmicky and unstructured to be exposed directly in the universe
   // but we need it in a publicly available place for reification to work
 
+  /** @group TreeBuilders */
   abstract class BuildApi {
     /** Selects type symbol with given simple name `name` from the defined members of `owner`.
      */