From 706091cadbfd3d3d89df4acc68ea910679005ec8 Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Wed, 10 Oct 2012 21:29:20 +0200 Subject: Grouping for reflection and macros and warning cleanup --- src/reflect/scala/reflect/api/Annotations.scala | 74 +- src/reflect/scala/reflect/api/BuildUtils.scala | 3 + src/reflect/scala/reflect/api/Exprs.scala | 6 +- src/reflect/scala/reflect/api/FlagSets.scala | 20 +- src/reflect/scala/reflect/api/Importers.scala | 19 +- src/reflect/scala/reflect/api/JavaMirrors.scala | 11 +- src/reflect/scala/reflect/api/JavaUniverse.scala | 5 +- src/reflect/scala/reflect/api/Mirror.scala | 27 +- src/reflect/scala/reflect/api/Mirrors.scala | 18 +- src/reflect/scala/reflect/api/Names.scala | 31 +- src/reflect/scala/reflect/api/Positions.scala | 9 +- src/reflect/scala/reflect/api/Printers.scala | 16 +- src/reflect/scala/reflect/api/Scopes.scala | 24 +- .../scala/reflect/api/StandardDefinitions.scala | 12 +- src/reflect/scala/reflect/api/TagInterop.scala | 2 + src/reflect/scala/reflect/api/Trees.scala | 758 +++++++++++++++++---- src/reflect/scala/reflect/api/TypeTags.scala | 17 +- src/reflect/scala/reflect/api/Types.scala | 192 +++++- src/reflect/scala/reflect/api/Universe.scala | 8 +- src/reflect/scala/reflect/macros/Context.scala | 2 +- src/reflect/scala/reflect/macros/Evals.scala | 2 +- src/reflect/scala/reflect/macros/Parsers.scala | 2 +- src/reflect/scala/reflect/macros/Universe.scala | 37 +- src/reflect/scala/reflect/macros/package.scala | 2 +- 24 files changed, 1046 insertions(+), 251 deletions(-) (limited to 'src') diff --git a/src/reflect/scala/reflect/api/Annotations.scala b/src/reflect/scala/reflect/api/Annotations.scala index 10d1e5df7a..a828b254fe 100644 --- a/src/reflect/scala/reflect/api/Annotations.scala +++ b/src/reflect/scala/reflect/api/Annotations.scala @@ -3,45 +3,50 @@ package api import scala.collection.immutable.ListMap -/** This trait provides annotation support for the reflection API. +/** This trait provides annotation support for the reflection API. * * The API distinguishes between two kinds of annotations: - * 1. ''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. - * 2. ''Scala annotations'': annotations on definitions or types produced by the Scala compiler. - * - * 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 + * 1. ''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. + * 1. ''Scala annotations'': annotations on definitions or types produced by the Scala compiler. + * + * 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 + * 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: + * [[scala.reflect.api.Annotations#JavaArgument]]. Instances of `JavaArgument` represent different kinds of Java annotation arguments: * - literals (primitive and string constants), - * - arrays and + * - arrays and * - nested annotations. */ trait Annotations { self: Universe => - /** Information about an annotation. */ + /** 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(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])] @@ -49,6 +54,7 @@ trait Annotations { self: Universe => /** 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. */ @@ -65,27 +71,38 @@ trait Annotations { self: Universe => 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 @@ -94,6 +111,7 @@ trait Annotations { self: Universe => /** 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. */ @@ -101,19 +119,25 @@ trait Annotations { self: Universe => } /** 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 @@ -122,6 +146,7 @@ trait Annotations { self: Universe => /** 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. */ @@ -129,19 +154,25 @@ trait Annotations { self: Universe => } /** 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 @@ -150,6 +181,7 @@ trait Annotations { self: Universe => /** 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. */ diff --git a/src/reflect/scala/reflect/api/BuildUtils.scala b/src/reflect/scala/reflect/api/BuildUtils.scala index b0de7f8d5a..0c8e81a220 100644 --- a/src/reflect/scala/reflect/api/BuildUtils.scala +++ b/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`. */ diff --git a/src/reflect/scala/reflect/api/Exprs.scala b/src/reflect/scala/reflect/api/Exprs.scala index 9b2cba1391..788fc889a8 100644 --- a/src/reflect/scala/reflect/api/Exprs.scala +++ b/src/reflect/scala/reflect/api/Exprs.scala @@ -19,17 +19,18 @@ import scala.reflect.runtime.{universe => ru} * * `Expr`s can also be created manually via the `Expr` companion object, but then the burden of providing a `TreeCreator` lies on the programmer. * Compile-time reflection via macros, as described in [[scala.reflect.macros.Aliases]], provides an easier way to instantiate exprs manually. - * Manual creation, however, is very rarely needed when working with runtime reflection. + * Manual creation, however, is very rarely needed when working with runtime reflection. * * `Expr` can be migrated from one mirror to another by using the `in` method. Migration means that all symbolic references * 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.package#universe]], the default mirror is typically [[scala.reflect.runtime.package#currentMirror]]. + * [[scala.reflect.runtime#universe]], the default mirror is typically [[scala.reflect.runtime#currentMirror]]. */ trait Exprs { self: Universe => /** Expr wraps an abstract syntax tree and tags it with its type. * The main source of information about exprs is the [[scala.reflect.api.Exprs]] page. + * @group Expressions */ trait Expr[+T] extends Equals with Serializable { /** @@ -123,6 +124,7 @@ trait Exprs { self: Universe => * in which case the tree first needs to be wrapped in an expr. * The main source of information about exprs is the [[scala.reflect.api.Exprs]] page. + * @group Expressions */ object Expr { def apply[T: WeakTypeTag](mirror: scala.reflect.api.Mirror[self.type], treec: TreeCreator): Expr[T] = new ExprImpl[T](mirror.asInstanceOf[Mirror], treec) diff --git a/src/reflect/scala/reflect/api/FlagSets.scala b/src/reflect/scala/reflect/api/FlagSets.scala index bb570bebbe..701442b632 100644 --- a/src/reflect/scala/reflect/api/FlagSets.scala +++ b/src/reflect/scala/reflect/api/FlagSets.scala @@ -32,26 +32,35 @@ import scala.language.implicitConversions */ trait FlagSets { self: Universe => - /** An abstract type representing sets of flags (like private, final, etc.) 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 + * @template + * @group Flags + */ type FlagSet /** A tag that preserves the identity of the `FlagSet` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val FlagSetTag: ClassTag[FlagSet] /** The API of `FlagSet` instances. * The main source of information about flag sets is the [[scala.reflect.api.FlagSets]] page. + * @group Flags */ trait FlagOps extends Any { /** Produces a flag set that's a union of this flag set and the provided flag set. */ def | (right: FlagSet): FlagSet } - /** The API of `FlagSet` instances. */ + /** The API of `FlagSet` instances. + * @group Flags + */ implicit def addFlagOps(left: FlagSet): FlagOps - /** A module that contains all possible values that can constitute flag sets. */ + /** A module that contains all possible values that can constitute flag sets. + * @group Flags + */ val Flag: FlagValues // Q: I have a pretty flag. Can I put it here? @@ -61,6 +70,7 @@ trait FlagSets { self: Universe => /** All possible values that can constitute flag sets. * The main source of information about flag sets is the [[scala.reflect.api.FlagSets]] page. + * @group Flags */ trait FlagValues { @@ -140,6 +150,8 @@ trait FlagSets { self: Universe => val DEFAULTINIT: FlagSet } - /** The empty set of flags */ + /** The empty set of flags + * @group Flags + */ val NoFlags: FlagSet } diff --git a/src/reflect/scala/reflect/api/Importers.scala b/src/reflect/scala/reflect/api/Importers.scala index f25f5a95e2..fde8794348 100644 --- a/src/reflect/scala/reflect/api/Importers.scala +++ b/src/reflect/scala/reflect/api/Importers.scala @@ -1,16 +1,16 @@ package scala.reflect package api -/** This trait provides support for importers, a facility to migrate reflection artifacts between universes. +/** This trait provides support for importers, a facility to migrate reflection artifacts between universes. * - * Reflection artifacts, such as symbols and types, are contained in universes. 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 + * Reflection artifacts, such as symbols and types, are contained in universes. 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 universes, which is reflected by the fact that types of artifacts - * from different universes are not compatible. By using importers, however, they be imported from one universe + * Reflection artifacts are firmly grounded in their universes, which is reflected by the fact that types of artifacts + * from different universes are not compatible. By using importers, 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 @@ -65,11 +65,14 @@ package api */ trait Importers { self: Universe => - /** Creates an importer that moves reflection artifacts between universes. */ + /** Creates an importer that moves reflection artifacts between universes. + * @group Importers + */ def mkImporter(from0: Universe): Importer { val from: from0.type } /** The API of importers. * The main source of information about importers is the [[scala.reflect.api.Importers]] page. + * @group Importers */ trait Importer { /** The source universe of reflection artifacts that will be processed. diff --git a/src/reflect/scala/reflect/api/JavaMirrors.scala b/src/reflect/scala/reflect/api/JavaMirrors.scala index e51047a7fe..9bc888b884 100644 --- a/src/reflect/scala/reflect/api/JavaMirrors.scala +++ b/src/reflect/scala/reflect/api/JavaMirrors.scala @@ -6,13 +6,18 @@ package api * This refinement equips mirrors with reflection capabilities for the JVM. `JavaMirror` can * convert Scala reflection artifacts (symbols and types) into Java reflection artifacts (classes) * and vice versa. It can also perform reflective invocations (getting/settings field values, calling methods, etc). + * @groupname JavaMirrors Java Mirrors */ trait JavaMirrors { self: JavaUniverse => - /** In runtime reflection universes, runtime representation of a class is [[java.lang.Class]]. */ + /** In runtime reflection universes, runtime representation of a class is `java.lang.Class`. + * @group JavaMirrors + */ type RuntimeClass = java.lang.Class[_] - /** In runtime reflection universes, mirrors are JavaMirrors. */ + /** In runtime reflection universes, mirrors are JavaMirrors. + * @group JavaMirrors + */ override type Mirror >: Null <: JavaMirror /** A refinement of [[scala.reflect.api.Mirror]] for runtime reflection using JVM classloaders. @@ -22,6 +27,7 @@ trait JavaMirrors { self: JavaUniverse => * become capable of performing reflective invocations (getting/settings field values, calling methods, etc). * * See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection. + * @group JavaMirrors */ trait JavaMirror extends scala.reflect.api.Mirror[self.type] with RuntimeMirror { val classLoader: ClassLoader @@ -30,6 +36,7 @@ trait JavaMirrors { self: JavaUniverse => /** Creates a runtime reflection mirror from a JVM classloader. * See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection. + * @group JavaMirrors */ def runtimeMirror(cl: ClassLoader): Mirror } diff --git a/src/reflect/scala/reflect/api/JavaUniverse.scala b/src/reflect/scala/reflect/api/JavaUniverse.scala index b899d1f6d7..0283a75177 100644 --- a/src/reflect/scala/reflect/api/JavaUniverse.scala +++ b/src/reflect/scala/reflect/api/JavaUniverse.scala @@ -6,10 +6,12 @@ package api * The refinement consists of an upgrade to the mirror API, which gets extended from [[scala.reflect.api.Mirror]] * to [[scala.reflect.api.JavaMirrors#JavaMirror]]. * - * See the [[docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for details on how to use runtime reflection. + * 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 */ trait JavaUniverse extends Universe with JavaMirrors { self => + /* @group JavaUniverse */ override def typeTagToManifest[T: ClassTag](mirror0: Any, tag: Universe # TypeTag[T]): Manifest[T] = { // SI-6239: make this conversion more precise val mirror = mirror0.asInstanceOf[Mirror] @@ -17,6 +19,7 @@ trait JavaUniverse extends Universe with JavaMirrors { self => Manifest.classType(runtimeClass).asInstanceOf[Manifest[T]] } + /* @group JavaUniverse */ override def manifestToTypeTag[T](mirror0: Any, manifest: Manifest[T]): Universe # TypeTag[T] = TypeTag(mirror0.asInstanceOf[Mirror], new TypeCreator { def apply[U <: Universe with Singleton](mirror: scala.reflect.api.Mirror[U]): U # Type = { diff --git a/src/reflect/scala/reflect/api/Mirror.scala b/src/reflect/scala/reflect/api/Mirror.scala index ae2c48fa14..60ba087933 100644 --- a/src/reflect/scala/reflect/api/Mirror.scala +++ b/src/reflect/scala/reflect/api/Mirror.scala @@ -4,30 +4,40 @@ package api /** * The base class for all mirrors. * - * See the [[docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for a description of mirrors + * See the [[http://docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for a description of mirrors * and infomation on getting started with Scala reflection API. * * 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. * * @tparam U the type of the universe this mirror belongs to. */ abstract class Mirror[U <: Universe with Singleton] { - /** The universe this mirror belongs to. */ + /** The universe this mirror belongs to. + * @group Mirror + */ val universe: U - /** The class symbol of the `_root_` package */ + /** The class symbol of the `_root_` package + * @group Mirror + */ def RootClass: U#ClassSymbol - /** The module symbol of the `_root_` package */ + /** The module symbol of the `_root_` package + * @group Mirror + */ def RootPackage: U#ModuleSymbol - /** The module class symbol of the default (unnamed) package */ + /** The module class symbol of the default (unnamed) package + * @group Mirror + */ def EmptyPackageClass: U#ClassSymbol - /** The module symbol of the default (unnamed) package */ + /** The module symbol of the default (unnamed) package + * @group Mirror + */ def EmptyPackage: U#ModuleSymbol /** The symbol corresponding to the globally accessible class with the @@ -71,6 +81,7 @@ abstract class Mirror[U <: Universe with Singleton] { * * In the example above, to load a symbol that corresponds to the class B declared in the object foo, * use staticModule("foo") to load the module symbol and then navigate typeSignature.members of its moduleClass. + * @group Mirror */ def staticClass(fullName: String): U#ClassSymbol @@ -97,11 +108,13 @@ abstract class Mirror[U <: Universe with Singleton] { * * In the example above, to load a symbol that corresponds to the object B declared in the object foo, * use staticModule("foo") to load the module symbol and then navigate typeSignature.members of its moduleClass. + * @group Mirror */ def staticModule(fullName: String): U#ModuleSymbol /** The symbol corresponding to a package with the * given fully qualified name `fullName`. + * @group Mirror */ def staticPackage(fullName: String): U#ModuleSymbol } diff --git a/src/reflect/scala/reflect/api/Mirrors.scala b/src/reflect/scala/reflect/api/Mirrors.scala index 1e742f4145..bebc9488dd 100644 --- a/src/reflect/scala/reflect/api/Mirrors.scala +++ b/src/reflect/scala/reflect/api/Mirrors.scala @@ -1,9 +1,9 @@ package scala.reflect package api -/** This trait provides support for Mirrors in the reflection API. +/** This trait provides support for Mirrors in the reflection API. * - * See the [[docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for a description of mirrors + * See the [[http://docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for a description of mirrors * and infomation on getting started with Scala reflection API. */ trait Mirrors { self: Universe => @@ -12,15 +12,19 @@ trait Mirrors { self: Universe => * * This abstract type conforms the base interface for all mirrors defined in [[scala.reflect.api.Mirror]] * and is gradually refined in specific universes (e.g. `Mirror` of a [[scala.reflect.api.JavaUniverse]] is capable of reflection). + * @group Mirrors */ type Mirror >: Null <: scala.reflect.api.Mirror[self.type] /** 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. + * @group Mirrors */ val rootMirror: Mirror - /** Abstracts the runtime representation of a class on the underlying platform. */ + /** Abstracts the runtime representation of a class on the underlying platform. + * @group Mirrors + */ type RuntimeClass >: Null // todo. an improvement might be having mirrors reproduce the structure of the reflection domain @@ -29,6 +33,7 @@ trait Mirrors { self: Universe => /** A mirror that reflects a runtime value. * See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection. + * @group Mirrors */ trait InstanceMirror { @@ -105,6 +110,7 @@ trait Mirrors { self: Universe => /** A mirror that reflects a field. * See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection. + * @group Mirrors */ trait FieldMirror { @@ -149,6 +155,7 @@ trait Mirrors { self: Universe => /** A mirror that reflects a method. * See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection. + * @group Mirrors */ trait MethodMirror { @@ -169,6 +176,7 @@ trait Mirrors { self: Universe => /** A mirror that reflects the instance or static parts of a runtime class. * See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection. + * @group Mirrors */ trait TemplateMirror { @@ -187,6 +195,7 @@ trait Mirrors { self: Universe => /** A mirror that reflects a Scala object definition or the static parts of a runtime class. * See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection. + * @group Mirrors */ trait ModuleMirror extends TemplateMirror { @@ -202,6 +211,7 @@ trait Mirrors { self: Universe => /** A mirror that reflects the instance parts of a runtime class. * See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection. + * @group Mirrors */ trait ClassMirror extends TemplateMirror { @@ -223,6 +233,7 @@ trait Mirrors { self: Universe => /** A mirror that reflects instances and static classes. * See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection. + * @group Mirrors */ trait ReflectiveMirror extends scala.reflect.api.Mirror[Mirrors.this.type] { @@ -260,6 +271,7 @@ trait Mirrors { self: Universe => /** The API of a mirror for a reflective universe. * See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection. + * @group Mirrors */ trait RuntimeMirror extends ReflectiveMirror { self => diff --git a/src/reflect/scala/reflect/api/Names.scala b/src/reflect/scala/reflect/api/Names.scala index dccdd6868b..7b66906499 100644 --- a/src/reflect/scala/reflect/api/Names.scala +++ b/src/reflect/scala/reflect/api/Names.scala @@ -2,11 +2,11 @@ package scala.reflect package api /** This trait defines Names (a Scala reflection concept) 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. - * + * same name can co-exist in an object. + * * @see [[http://docs.scala-lang.org/overviews/reflection/overview.html]]. * === Examples === @@ -19,39 +19,52 @@ package api trait Names { /** An implicit conversion from String to TermName. * Enables an alternative notation `"map": TermName` as opposed to `newTermName("map")`. + * @group Names */ implicit def stringToTermName(s: String): TermName = newTermName(s) /** An implicit conversion from String to TypeName. * Enables an alternative notation `"List": TypeName` as opposed to `newTypeName("List")`. + * @group Names */ implicit def stringToTypeName(s: String): TypeName = newTypeName(s) - /** The abstract type of names. */ + /** The abstract type of names. + * @group Names + */ type Name >: Null <: NameApi /** A tag that preserves the identity of the `Name` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val NameTag: ClassTag[Name] - /** The abstract type of names representing terms. */ + /** The abstract type of names representing terms. + * @group Names + */ type TypeName >: Null <: Name /** A tag that preserves the identity of the `TypeName` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ - implicit val TypeNameTag: ClassTag[TypeName] +implicit val TypeNameTag: ClassTag[TypeName] - /** The abstract type of names representing types. */ + /** The abstract type of names representing types. + * @group Names + */ type TermName >: Null <: Name /** A tag that preserves the identity of the `TermName` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TermNameTag: ClassTag[TermName] - /** The API of Name instances. */ + /** The API of Name instances. + * @group API + */ abstract class NameApi { /** Checks wether the name is a a term name */ def isTermName: Boolean @@ -85,10 +98,12 @@ trait Names { } /** Create a new term name. + * @group Names */ def newTermName(s: String): TermName /** Creates a new type name. + * @group Names */ def newTypeName(s: String): TypeName } diff --git a/src/reflect/scala/reflect/api/Positions.scala b/src/reflect/scala/reflect/api/Positions.scala index bbb1fe45c4..ec1cf21c75 100644 --- a/src/reflect/scala/reflect/api/Positions.scala +++ b/src/reflect/scala/reflect/api/Positions.scala @@ -10,18 +10,23 @@ trait Positions { /** Defines a universe-specific notion of positions. * The main documentation entry about positions is located at [[scala.reflect.api.Position]]. + * @group Positions */ type Position >: Null <: scala.reflect.api.Position { type Pos = Position } /** A tag that preserves the identity of the `Position` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val PositionTag: ClassTag[Position] - /** A special "missing" position. */ + /** A special "missing" position. + * @group Positions + */ val NoPosition: Position /** Assigns a given position to all position-less nodes of a given AST. + * @group Positions */ def atPos[T <: Tree](pos: Position)(tree: T): T @@ -29,6 +34,7 @@ trait Positions { * The point of the wrapping position is the point of the default position. * If some of the trees are ranges, returns a range position enclosing all ranges * Otherwise returns default position. + * @group Positions */ def wrappingPos(default: Position, trees: List[Tree]): Position @@ -36,6 +42,7 @@ trait Positions { * The point of the wrapping position is the point of the first trees' position. * If all some the trees are non-synthetic, returns a range position enclosing the non-synthetic trees * Otherwise returns a synthetic offset position to point. + * @group Positions */ def wrappingPos(trees: List[Tree]): Position } diff --git a/src/reflect/scala/reflect/api/Printers.scala b/src/reflect/scala/reflect/api/Printers.scala index 831c4ae331..b7157af153 100644 --- a/src/reflect/scala/reflect/api/Printers.scala +++ b/src/reflect/scala/reflect/api/Printers.scala @@ -131,6 +131,7 @@ import java.io.{ PrintWriter, StringWriter } */ trait Printers { self: Universe => + /** @group Printers */ protected trait TreePrinter { def print(args: Any*) protected var printTypes = false @@ -147,13 +148,16 @@ trait Printers { self: Universe => def withoutMirrors: this.type = { printMirrors = false; this } } + /** @group Printers */ case class BooleanFlag(val value: Option[Boolean]) + /** @group Printers */ object BooleanFlag { import scala.language.implicitConversions implicit def booleanToBooleanFlag(value: Boolean): BooleanFlag = BooleanFlag(Some(value)) implicit def optionToBooleanFlag(value: Option[Boolean]): BooleanFlag = BooleanFlag(value) } + /** @group Printers */ protected def render(what: Any, mkPrinter: PrintWriter => TreePrinter, printTypes: BooleanFlag = None, printIds: BooleanFlag = None, printKinds: BooleanFlag = None, printMirrors: BooleanFlag = None): String = { val buffer = new StringWriter() val writer = new PrintWriter(buffer) @@ -167,41 +171,51 @@ trait Printers { self: Universe => buffer.toString } - /** By default trees are printed with `show` */ + /** By default trees are printed with `show` + * @group Printers + */ override protected def treeToString(tree: Tree) = show(tree) /** Renders a prettified representation of a reflection artifact. * Typically it looks very close to the Scala code it represents. + * @group Printers */ def show(any: Any, printTypes: BooleanFlag = None, printIds: BooleanFlag = None, printKinds: BooleanFlag = None, printMirrors: BooleanFlag = None): String = render(any, newTreePrinter(_), printTypes, printIds, printKinds, printMirrors) /** Hook to define what `show(...)` means. + * @group Printers */ protected def newTreePrinter(out: PrintWriter): TreePrinter /** Renders internal structure of a reflection artifact. + * @group Printers */ def showRaw(any: Any, printTypes: BooleanFlag = None, printIds: BooleanFlag = None, printKinds: BooleanFlag = None, printMirrors: BooleanFlag = None): String = render(any, newRawTreePrinter(_), printTypes, printIds, printKinds, printMirrors) /** Hook to define what `showRaw(...)` means. + * @group Printers */ protected def newRawTreePrinter(out: PrintWriter): TreePrinter /** Renders a prettified representation of a name. + * @group Printers */ def show(name: Name): String /** Renders internal structure of a name. + * @group Printers */ def showRaw(name: Name): String = name.toString /** Renders a prettified representation of a flag set. + * @group Printers */ def show(flags: FlagSet): String /** Renders internal structure of a flag set. + * @group Printers */ def showRaw(flags: FlagSet): String = flags.toString } diff --git a/src/reflect/scala/reflect/api/Scopes.scala b/src/reflect/scala/reflect/api/Scopes.scala index ec9aba6567..80683c8e76 100644 --- a/src/reflect/scala/reflect/api/Scopes.scala +++ b/src/reflect/scala/reflect/api/Scopes.scala @@ -17,24 +17,37 @@ package api */ trait Scopes { self: Universe => - /** The base type of all scopes. */ + /** The base type of all scopes. + * @template + * @group Scopes + */ type Scope >: Null <: ScopeApi - /** The API that all scopes support */ + /** The API that all scopes support + * @group API + */ trait ScopeApi extends Iterable[Symbol] /** A tag that preserves the identity of the `Scope` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ScopeTag: ClassTag[Scope] - /** Create a new scope with the given initial elements. */ + /** Create a new scope with the given initial elements. + * @group Scopes + */ def newScopeWith(elems: Symbol*): Scope - /** The type of member scopes, as in class definitions, for example. */ + /** The type of member scopes, as in class definitions, for example. + * @template + * @group Scopes + */ type MemberScope >: Null <: Scope with MemberScopeApi - /** The API that all member scopes support */ + /** The API that all member scopes support + * @group API + */ trait MemberScopeApi extends ScopeApi { /** Sorts the symbols included in this scope so that: * 1) Symbols appear in the linearization order of their owners. @@ -46,6 +59,7 @@ trait Scopes { self: Universe => /** A tag that preserves the identity of the `MemberScope` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val MemberScopeTag: ClassTag[MemberScope] } \ No newline at end of file diff --git a/src/reflect/scala/reflect/api/StandardDefinitions.scala b/src/reflect/scala/reflect/api/StandardDefinitions.scala index cca9440302..e1eadde3ad 100644 --- a/src/reflect/scala/reflect/api/StandardDefinitions.scala +++ b/src/reflect/scala/reflect/api/StandardDefinitions.scala @@ -13,10 +13,14 @@ package api trait StandardDefinitions { self: Universe => - /** A value containing all standard definitions. */ + /** A value containing all standard definitions in [[DefinitionsApi]] + * @group Definitions + */ val definitions: DefinitionsApi - /** Defines standard symbols (and types via its base trait). */ + /** Defines standard symbols (and types via its base trait). + * @group API + */ trait DefinitionsApi extends StandardTypes { /** The module class symbol of package `scala`. */ def ScalaPackageClass: ClassSymbol @@ -252,7 +256,9 @@ trait StandardDefinitions { def ScalaNumericValueClasses: List[ClassSymbol] } - /** Defines standard types. */ + /** Defines standard types. + * @group Definitions + */ trait StandardTypes { /** The type of primitive type `Unit`. */ val UnitTpe: Type diff --git a/src/reflect/scala/reflect/api/TagInterop.scala b/src/reflect/scala/reflect/api/TagInterop.scala index 4653eb975f..b495c3f50c 100644 --- a/src/reflect/scala/reflect/api/TagInterop.scala +++ b/src/reflect/scala/reflect/api/TagInterop.scala @@ -16,6 +16,7 @@ trait TagInterop { self: Universe => * {{{ * typeTagToManifest(scala.reflect.runtime.currentMirror, implicitly[TypeTag[String]]) * }}} + * @group Tags */ def typeTagToManifest[T: ClassTag](mirror: Any, tag: Universe#TypeTag[T]): Manifest[T] = throw new UnsupportedOperationException("This universe does not support tag -> manifest conversions. Use a JavaUniverse, e.g. the scala.reflect.runtime.universe.") @@ -29,6 +30,7 @@ trait TagInterop { self: Universe => * {{{ * manifestToTypeTag(scala.reflect.runtime.currentMirror, implicitly[Manifest[String]]) * }}} + * @group Tags */ def manifestToTypeTag[T](mirror: Any, manifest: Manifest[T]): Universe#TypeTag[T] = throw new UnsupportedOperationException("This universe does not support manifest -> tag conversions. Use a JavaUniverse, e.g. the scala.reflect.runtime.universe.") diff --git a/src/reflect/scala/reflect/api/Trees.scala b/src/reflect/scala/reflect/api/Trees.scala index 03d62c3bb9..1142bb042f 100644 --- a/src/reflect/scala/reflect/api/Trees.scala +++ b/src/reflect/scala/reflect/api/Trees.scala @@ -6,40 +6,50 @@ package scala.reflect 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#Tree Tree]]. - * - * Trees are immutable, except for three fields + * +* All tree node types are sub types of [[scala.reflect.api.Trees#Tree Tree]]. + * + * 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. - * + * * [[scala.reflect.api.Universe#showRaw showRaw]] can be used to get a readable representation of a tree. * * === Examples === * `Literal(Constant(5))` creates an AST representing a literal 5 in Scala source code. - * + * * `Apply(Select(Select(This(newTypeName("scala")), newTermName("Predef")), newTermName("print")), List(Literal(Constant("Hello World"))))` * creates an AST representing `print("Hello World")`. - * + * * `import scala.reflect.runtime.universe.{reify,showRaw}` - * `print( showRaw( reify{5}.tree ) )` // prints Literal(Constant(5)) + * `print( showRaw( reify{5}.tree ) )` // prints Literal(Constant(5)) * * @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 + * @groupname Copying Tree Copying + * @groupprio Copying 1 */ trait Trees { self: Universe => - /** The type of Scala abstract syntax trees. */ + /** The type of Scala abstract syntax trees. + * @group Trees + * @template + */ type Tree >: Null <: TreeApi /** A tag that preserves the identity of the `Tree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TreeTag: ClassTag[Tree] /** The API that all trees support. * The main source of information about trees is the [[scala.reflect.api.Trees]] page. + * @group API */ trait TreeApi extends Product { this: Tree => /** Does this tree represent a definition? (of a method, of a class, etc) */ @@ -69,7 +79,7 @@ trait Trees { self: Universe => * Some node factory methods set `tpe` immediately after creation. * * When the typechecker encounters a tree with a non-null tpe, - * it will assume it to be correct and not check it again. This means one has + * it will assume it to be correct and not check it again. This means one has * to be careful not to erase the `tpe` field of subtrees. */ def tpe: Type @@ -163,65 +173,89 @@ trait Trees { self: Universe => override def toString: String = treeToString(this) } - /** Obtains string representation of a tree */ + /** Obtains string representation of a tree + * @group Trees + */ protected def treeToString(tree: Tree): String - /** The empty tree */ + /** The empty tree + * @group Trees + */ val EmptyTree: Tree /** A tree for a term. Not all trees representing terms are TermTrees; use isTerm * to reliably identify terms. + * @group Trees + * @template */ type TermTree >: Null <: AnyRef with Tree with TermTreeApi /** A tag that preserves the identity of the `TermTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TermTreeTag: ClassTag[TermTree] - /** The API that all term trees support */ + /** The API that all term trees support + * @group API + */ trait TermTreeApi extends TreeApi { this: TermTree => } /** A tree for a type. Not all trees representing types are TypTrees; use isType * to reliably identify types. + * @group Trees + * @template */ type TypTree >: Null <: AnyRef with Tree with TypTreeApi /** A tag that preserves the identity of the `TypTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TypTreeTag: ClassTag[TypTree] - /** The API that all typ trees support */ + /** The API that all typ trees support + * @group API + */ trait TypTreeApi extends TreeApi { this: TypTree => } /** A tree with a mutable symbol field, initialized to NoSymbol. + * @group Trees + * @template */ type SymTree >: Null <: AnyRef with Tree with SymTreeApi /** A tag that preserves the identity of the `SymTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val SymTreeTag: ClassTag[SymTree] - /** The API that all sym trees support */ + /** The API that all sym trees support + * @group API + */ trait SymTreeApi extends TreeApi { this: SymTree => /** @inheritdoc */ def symbol: Symbol } /** A tree with a name - effectively, a DefTree or RefTree. + * @group Trees + * @template */ type NameTree >: Null <: AnyRef with Tree with NameTreeApi /** A tag that preserves the identity of the `NameTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val NameTreeTag: ClassTag[NameTree] - /** The API that all name trees support */ + /** The API that all name trees support + * @group API + */ trait NameTreeApi extends TreeApi { this: NameTree => /** The underlying name. * For example, the `` part of `Ident("List": TermName)`. @@ -232,15 +266,20 @@ trait Trees { self: Universe => /** A tree which references a symbol-carrying entity. * References one, as opposed to defining one; definitions * are in DefTrees. + * @group Trees + * @template */ type RefTree >: Null <: SymTree with NameTree with RefTreeApi /** A tag that preserves the identity of the `RefTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val RefTreeTag: ClassTag[RefTree] - /** The API that all ref trees support */ + /** The API that all ref trees support + * @group API + */ trait RefTreeApi extends SymTreeApi with NameTreeApi { this: RefTree => /** The qualifier of the reference. * For example, the `` part of `Select("scala": TermName, "List": TermName)`. @@ -253,15 +292,20 @@ trait Trees { self: Universe => } /** A tree which defines a symbol-carrying entity. + * @group Trees + * @template */ type DefTree >: Null <: SymTree with NameTree with DefTreeApi /** A tag that preserves the identity of the `DefTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val DefTreeTag: ClassTag[DefTree] - /** The API that all def trees support */ + /** The API that all def trees support + * @group API + */ trait DefTreeApi extends SymTreeApi with NameTreeApi { this: DefTree => /** @inheritdoc */ def name: Name @@ -269,43 +313,56 @@ trait Trees { self: Universe => /** Common base class for all member definitions: types, classes, * objects, packages, vals and vars, defs. + * @group Trees + * @template */ type MemberDef >: Null <: DefTree with MemberDefApi /** A tag that preserves the identity of the `MemberDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val MemberDefTag: ClassTag[MemberDef] - /** The API that all member defs support */ + /** The API that all member defs support + * @group API + */ trait MemberDefApi extends DefTreeApi { this: MemberDef => /** Modifiers of the declared member. */ def mods: Modifiers } /** A packaging, such as `package pid { stats }` + * @group Trees + * @template */ type PackageDef >: Null <: MemberDef with PackageDefApi /** A tag that preserves the identity of the `PackageDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val PackageDefTag: ClassTag[PackageDef] - /** The constructor/deconstructor for `PackageDef` instances. */ + /** The constructor/deconstructor for `PackageDef` instances. + * @group Extractors + */ val PackageDef: PackageDefExtractor /** An extractor class to create and pattern match with syntax `PackageDef(pid, stats)`. * This AST node corresponds to the following Scala code: * * `package` pid { stats } + * @group Extractors */ abstract class PackageDefExtractor { def apply(pid: RefTree, stats: List[Tree]): PackageDef def unapply(packageDef: PackageDef): Option[(RefTree, List[Tree])] } - /** The API that all package defs support */ + /** The API that all package defs support + * @group API + */ trait PackageDefApi extends MemberDefApi { this: PackageDef => /** The (possibly, fully-qualified) name of the package. */ val pid: RefTree @@ -315,30 +372,40 @@ trait Trees { self: Universe => } /** A common base class for class and object definitions. + * @group Trees + * @template */ type ImplDef >: Null <: MemberDef with ImplDefApi /** A tag that preserves the identity of the `ImplDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ImplDefTag: ClassTag[ImplDef] - /** The API that all impl defs support */ + /** The API that all impl defs support + * @group API + */ trait ImplDefApi extends MemberDefApi { this: ImplDef => /** The body of the definition. */ val impl: Template } /** A class definition. + * @group Trees + * @template */ type ClassDef >: Null <: ImplDef with ClassDefApi /** A tag that preserves the identity of the `ClassDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ClassDefTag: ClassTag[ClassDef] - /** The constructor/deconstructor for `ClassDef` instances. */ + /** The constructor/deconstructor for `ClassDef` instances. + * @group Extractors + */ val ClassDef: ClassDefExtractor /** An extractor class to create and pattern match with syntax `ClassDef(mods, name, tparams, impl)`. @@ -349,13 +416,16 @@ trait Trees { self: Universe => * Where impl stands for: * * `extends` parents { defs } + * @group Extractors */ abstract class ClassDefExtractor { def apply(mods: Modifiers, name: TypeName, tparams: List[TypeDef], impl: Template): ClassDef def unapply(classDef: ClassDef): Option[(Modifiers, TypeName, List[TypeDef], Template)] } - /** The API that all class defs support */ + /** The API that all class defs support + * @group API + */ trait ClassDefApi extends ImplDefApi { this: ClassDef => /** @inheritdoc */ val mods: Modifiers @@ -373,15 +443,20 @@ trait Trees { self: Universe => /** An object definition, e.g. `object Foo`. Internally, objects are * quite frequently called modules to reduce ambiguity. * Eliminated by compiler phase refcheck. + * @group Trees + * @template */ type ModuleDef >: Null <: ImplDef with ModuleDefApi /** A tag that preserves the identity of the `ModuleDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ModuleDefTag: ClassTag[ModuleDef] - /** The constructor/deconstructor for `ModuleDef` instances. */ + /** The constructor/deconstructor for `ModuleDef` instances. + * @group Extractors + */ val ModuleDef: ModuleDefExtractor /** An extractor class to create and pattern match with syntax `ModuleDef(mods, name, impl)`. @@ -392,13 +467,16 @@ trait Trees { self: Universe => * Where impl stands for: * * `extends` parents { defs } + * @group Extractors */ abstract class ModuleDefExtractor { def apply(mods: Modifiers, name: TermName, impl: Template): ModuleDef def unapply(moduleDef: ModuleDef): Option[(Modifiers, TermName, Template)] } - /** The API that all module defs support */ + /** The API that all module defs support + * @group API + */ trait ModuleDefApi extends ImplDefApi { this: ModuleDef => /** @inheritdoc */ val mods: Modifiers @@ -411,15 +489,20 @@ trait Trees { self: Universe => } /** A common base class for ValDefs and DefDefs. + * @group Trees + * @template */ type ValOrDefDef >: Null <: MemberDef with ValOrDefDefApi /** A tag that preserves the identity of the `ValOrDefDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ValOrDefDefTag: ClassTag[ValOrDefDef] - /** The API that all val defs and def defs support */ + /** The API that all val defs and def defs support + * @group API + */ trait ValOrDefDefApi extends MemberDefApi { this: ValOrDefDef => /** @inheritdoc */ def name: Name // can't be a TermName because macros can be type names. @@ -443,15 +526,20 @@ trait Trees { self: Universe => * - lazy values, e.g. "lazy val x" - the LAZY flag set in mods * - method parameters, see vparamss in [[scala.reflect.api.Trees#DefDef]] - the PARAM flag is set in mods * - explicit self-types, e.g. class A { self: Bar => } + * @group Trees + * @template */ type ValDef >: Null <: ValOrDefDef with ValDefApi /** A tag that preserves the identity of the `ValDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ValDefTag: ClassTag[ValDef] - /** The constructor/deconstructor for `ValDef` instances. */ + /** The constructor/deconstructor for `ValDef` instances. + * @group Extractors + */ val ValDef: ValDefExtractor /** An extractor class to create and pattern match with syntax `ValDef(mods, name, tpt, rhs)`. @@ -467,13 +555,16 @@ trait Trees { self: Universe => * * If the type of a value is not specified explicitly (i.e. is meant to be inferred), * this is expressed by having `tpt` set to `TypeTree()` (but not to an `EmptyTree`!). + * @group Extractors */ abstract class ValDefExtractor { def apply(mods: Modifiers, name: TermName, tpt: Tree, rhs: Tree): ValDef def unapply(valDef: ValDef): Option[(Modifiers, TermName, Tree, Tree)] } - /** The API that all val defs support */ + /** The API that all val defs support + * @group API + */ trait ValDefApi extends ValOrDefDefApi { this: ValDef => /** @inheritdoc */ val mods: Modifiers @@ -490,15 +581,20 @@ trait Trees { self: Universe => /** A method or macro definition. * @param name The name of the method or macro. Can be a type name in case this is a type macro + * @group Trees + * @template */ type DefDef >: Null <: ValOrDefDef with DefDefApi /** A tag that preserves the identity of the `DefDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val DefDefTag: ClassTag[DefDef] - /** The constructor/deconstructor for `DefDef` instances. */ + /** The constructor/deconstructor for `DefDef` instances. + * @group Extractors + */ val DefDef: DefDefExtractor /** An extractor class to create and pattern match with syntax `DefDef(mods, name, tparams, vparamss, tpt, rhs)`. @@ -508,13 +604,16 @@ trait Trees { self: Universe => * * If the return type is not specified explicitly (i.e. is meant to be inferred), * this is expressed by having `tpt` set to `TypeTree()` (but not to an `EmptyTree`!). + * @group Extractors */ abstract class DefDefExtractor { def apply(mods: Modifiers, name: Name, tparams: List[TypeDef], vparamss: List[List[ValDef]], tpt: Tree, rhs: Tree): DefDef def unapply(defDef: DefDef): Option[(Modifiers, Name, List[TypeDef], List[List[ValDef]], Tree, Tree)] } - /** The API that all def defs support */ + /** The API that all def defs support + * @group API + */ trait DefDefApi extends ValOrDefDefApi { this: DefDef => /** @inheritdoc */ val mods: Modifiers @@ -537,15 +636,20 @@ trait Trees { self: Universe => /** An abstract type, a type parameter, or a type alias. * Eliminated by erasure. + * @group Trees + * @template */ type TypeDef >: Null <: MemberDef with TypeDefApi /** A tag that preserves the identity of the `TypeDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TypeDefTag: ClassTag[TypeDef] - /** The constructor/deconstructor for `TypeDef` instances. */ + /** The constructor/deconstructor for `TypeDef` instances. + * @group Extractors + */ val TypeDef: TypeDefExtractor /** An extractor class to create and pattern match with syntax `TypeDef(mods, name, tparams, rhs)`. @@ -558,13 +662,16 @@ trait Trees { self: Universe => * First usage illustrates `TypeDefs` representing type aliases and type parameters. * Second usage illustrates `TypeDefs` representing abstract types, * where lo and hi are both `TypeBoundsTrees` and `Modifier.deferred` is set in mods. + * @group Extractors */ abstract class TypeDefExtractor { def apply(mods: Modifiers, name: TypeName, tparams: List[TypeDef], rhs: Tree): TypeDef def unapply(typeDef: TypeDef): Option[(Modifiers, TypeName, List[TypeDef], Tree)] } - /** The API that all type defs support */ + /** The API that all type defs support + * @group API + */ trait TypeDefApi extends MemberDefApi { this: TypeDef => /** @inheritdoc */ val mods: Modifiers @@ -594,15 +701,20 @@ trait Trees { self: Universe => * assigned to the Idents. * * Forward jumps within a block are allowed. + * @group Trees + * @template */ type LabelDef >: Null <: DefTree with TermTree with LabelDefApi /** A tag that preserves the identity of the `LabelDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val LabelDefTag: ClassTag[LabelDef] - /** The constructor/deconstructor for `LabelDef` instances. */ + /** The constructor/deconstructor for `LabelDef` instances. + * @group Extractors + */ val LabelDef: LabelDefExtractor /** An extractor class to create and pattern match with syntax `LabelDef(name, params, rhs)`. @@ -611,18 +723,21 @@ trait Trees { self: Universe => * It is used for tailcalls and like. * For example, while/do are desugared to label defs as follows: * {{{ - * while (cond) body ==> LabelDef($L, List(), if (cond) { body; L$() } else ()) + * while (cond) body ==> LabelDef(\$L, List(), if (cond) { body; L\$() } else ()) * }}} * {{{ - * do body while (cond) ==> LabelDef($L, List(), body; if (cond) L$() else ()) + * do body while (cond) ==> LabelDef(\$L, List(), body; if (cond) L\$() else ()) * }}} + * @group Extractors */ abstract class LabelDefExtractor { def apply(name: TermName, params: List[Ident], rhs: Tree): LabelDef def unapply(labelDef: LabelDef): Option[(TermName, List[Ident], Tree)] } - /** The API that all label defs support */ + /** The API that all label defs support + * @group API + */ trait LabelDefApi extends DefTreeApi with TermTreeApi { this: LabelDef => /** @inheritdoc */ val name: TermName @@ -648,26 +763,34 @@ trait Trees { self: Universe => * @param namePos its position or -1 if undefined * @param rename the name the import is renamed to (== name if no renaming) * @param renamePos the position of the rename or -1 if undefined + * @group Trees + * @template */ type ImportSelector >: Null <: AnyRef with ImportSelectorApi /** A tag that preserves the identity of the `ImportSelector` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ImportSelectorTag: ClassTag[ImportSelector] - /** The constructor/deconstructor for `ImportSelector` instances. */ + /** The constructor/deconstructor for `ImportSelector` instances. + * @group Extractors + */ val ImportSelector: ImportSelectorExtractor /** An extractor class to create and pattern match with syntax `ImportSelector(name:, namePos, rename, renamePos)`. * This is not an AST node, it is used as a part of the `Import` node. + * @group Extractors */ abstract class ImportSelectorExtractor { def apply(name: Name, namePos: Int, rename: Name, renamePos: Int): ImportSelector def unapply(importSelector: ImportSelector): Option[(Name, Int, Name, Int)] } - /** The API that all import selectors support */ + /** The API that all import selectors support + * @group API + */ trait ImportSelectorApi { this: ImportSelector => /** The imported name. */ val name: Name @@ -692,15 +815,20 @@ trait Trees { self: Universe => * * @param expr * @param selectors + * @group Trees + * @template */ type Import >: Null <: SymTree with ImportApi /** A tag that preserves the identity of the `Import` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ImportTag: ClassTag[Import] - /** The constructor/deconstructor for `Import` instances. */ + /** The constructor/deconstructor for `Import` instances. + * @group Extractors + */ val Import: ImportExtractor /** An extractor class to create and pattern match with syntax `Import(expr, selectors)`. @@ -719,13 +847,16 @@ trait Trees { self: Universe => * * The symbol of an `Import` is an import symbol @see Symbol.newImport. * It's used primarily as a marker to check that the import has been typechecked. + * @group Extractors */ abstract class ImportExtractor { def apply(expr: Tree, selectors: List[ImportSelector]): Import def unapply(import_ : Import): Option[(Tree, List[ImportSelector])] } - /** The API that all imports support */ + /** The API that all imports support + * @group API + */ trait ImportApi extends SymTreeApi { this: Import => /** The qualifier of the import. * See the example for [[scala.reflect.api.Trees#ImportExtractor]]. @@ -742,15 +873,20 @@ trait Trees { self: Universe => * * @param parents * @param body + * @group Trees + * @template */ type Template >: Null <: SymTree with TemplateApi /** A tag that preserves the identity of the `Template` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TemplateTag: ClassTag[Template] - /** The constructor/deconstructor for `Template` instances. */ + /** The constructor/deconstructor for `Template` instances. + * @group Extractors + */ val Template: TemplateExtractor /** An extractor class to create and pattern match with syntax `Template(parents, self, body)`. @@ -770,13 +906,16 @@ trait Trees { self: Universe => * def bar // owner is local dummy * } * } + * @group Extractors */ abstract class TemplateExtractor { def apply(parents: List[Tree], self: ValDef, body: List[Tree]): Template def unapply(template: Template): Option[(List[Tree], ValDef, List[Tree])] } - /** The API that all templates support */ + /** The API that all templates support + * @group API + */ trait TemplateApi extends SymTreeApi { this: Template => /** Superclasses of the template. */ val parents: List[Tree] @@ -791,15 +930,21 @@ trait Trees { self: Universe => val body: List[Tree] } - /** Block of expressions (semicolon separated expressions) */ + /** Block of expressions (semicolon separated expressions) + * @group Trees + * @template + */ type Block >: Null <: TermTree with BlockApi /** A tag that preserves the identity of the `Block` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val BlockTag: ClassTag[Block] - /** The constructor/deconstructor for `Block` instances. */ + /** The constructor/deconstructor for `Block` instances. + * @group Extractors + */ val Block: BlockExtractor /** An extractor class to create and pattern match with syntax `Block(stats, expr)`. @@ -808,13 +953,16 @@ trait Trees { self: Universe => * { stats; expr } * * If the block is empty, the `expr` is set to `Literal(Constant(()))`. + * @group Extractors */ abstract class BlockExtractor { def apply(stats: List[Tree], expr: Tree): Block def unapply(block: Block): Option[(List[Tree], Tree)] } - /** The API that all blocks support */ + /** The API that all blocks support + * @group API + */ trait BlockApi extends TermTreeApi { this: Block => /** All, but the last, expressions in the block. * Can very well be an empty list. @@ -828,15 +976,20 @@ trait Trees { self: Universe => /** Case clause in a pattern match. * (except for occurrences in switch statements). * Eliminated by compiler phases patmat (in the new pattern matcher of 2.10) or explicitouter (in the old pre-2.10 pattern matcher) + * @group Trees + * @template */ type CaseDef >: Null <: AnyRef with Tree with CaseDefApi /** A tag that preserves the identity of the `CaseDef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val CaseDefTag: ClassTag[CaseDef] - /** The constructor/deconstructor for `CaseDef` instances. */ + /** The constructor/deconstructor for `CaseDef` instances. + * @group Extractors + */ val CaseDef: CaseDefExtractor /** An extractor class to create and pattern match with syntax `CaseDef(pat, guard, body)`. @@ -846,13 +999,16 @@ trait Trees { self: Universe => * * If the guard is not present, the `guard` is set to `EmptyTree`. * If the body is not specified, the `body` is set to `Literal(Constant())` + * @group Extractors */ abstract class CaseDefExtractor { def apply(pat: Tree, guard: Tree, body: Tree): CaseDef def unapply(caseDef: CaseDef): Option[(Tree, Tree, Tree)] } - /** The API that all case defs support */ + /** The API that all case defs support + * @group API + */ trait CaseDefApi extends TreeApi { this: CaseDef => /** The pattern of the pattern matching clause. */ val pat: Tree @@ -873,28 +1029,36 @@ trait Trees { self: Universe => * 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(...))) + * @group Trees + * @template */ type Alternative >: Null <: TermTree with AlternativeApi /** A tag that preserves the identity of the `Alternative` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val AlternativeTag: ClassTag[Alternative] - /** The constructor/deconstructor for `Alternative` instances. */ + /** The constructor/deconstructor for `Alternative` instances. + * @group Extractors + */ val Alternative: AlternativeExtractor /** An extractor class to create and pattern match with syntax `Alternative(trees)`. * This AST node corresponds to the following Scala code: * * pat1 | ... | patn + * @group Extractors */ abstract class AlternativeExtractor { def apply(trees: List[Tree]): Alternative def unapply(alternative: Alternative): Option[List[Tree]] } - /** The API that all alternatives support */ + /** The API that all alternatives support + * @group API + */ trait AlternativeApi extends TermTreeApi { this: Alternative => /** Alternatives of the pattern matching clause. */ val trees: List[Tree] @@ -903,28 +1067,36 @@ trait Trees { self: Universe => /** Repetition of pattern. * * Eliminated by compiler phases patmat (in the new pattern matcher of 2.10) or explicitouter (in the old pre-2.10 pattern matcher). + * @group Trees + * @template */ type Star >: Null <: TermTree with StarApi /** A tag that preserves the identity of the `Star` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val StarTag: ClassTag[Star] - /** The constructor/deconstructor for `Star` instances. */ + /** The constructor/deconstructor for `Star` instances. + * @group Extractors + */ val Star: StarExtractor /** An extractor class to create and pattern match with syntax `Star(elem)`. * This AST node corresponds to the following Scala code: * * pat* + * @group Extractors */ abstract class StarExtractor { def apply(elem: Tree): Star def unapply(star: Star): Option[Tree] } - /** The API that all stars support */ + /** The API that all stars support + * @group API + */ trait StarApi extends TermTreeApi { this: Star => /** The quantified pattern. */ val elem: Tree @@ -936,28 +1108,36 @@ trait Trees { self: Universe => * * @param name * @param body + * @group Trees + * @template */ type Bind >: Null <: DefTree with BindApi /** A tag that preserves the identity of the `Bind` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val BindTag: ClassTag[Bind] - /** The constructor/deconstructor for `Bind` instances. */ + /** The constructor/deconstructor for `Bind` instances. + * @group Extractors + */ val Bind: BindExtractor /** An extractor class to create and pattern match with syntax `Bind(name, body)`. * This AST node corresponds to the following Scala code: * * pat* + * @group Extractors */ abstract class BindExtractor { def apply(name: Name, body: Tree): Bind def unapply(bind: Bind): Option[(Name, Tree)] } - /** The API that all binds support */ + /** The API that all binds support + * @group API + */ trait BindApi extends DefTreeApi { this: Bind => /** The name that can be used to refer to this fragment of the matched expression. * The `list` part of the `list @ List(x, y)`. @@ -997,27 +1177,35 @@ trait Trees { self: Universe => * }}} * * 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). + * @group Trees + * @template */ type UnApply >: Null <: TermTree with UnApplyApi /** A tag that preserves the identity of the `UnApply` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val UnApplyTag: ClassTag[UnApply] - /** The constructor/deconstructor for `UnApply` instances. */ + /** The constructor/deconstructor for `UnApply` instances. + * @group Extractors + */ val UnApply: UnApplyExtractor /** An extractor class to create and pattern match with syntax `UnApply(fun, args)`. * This AST node does not have direct correspondence to Scala code, * and is introduced when typechecking pattern matches and `try` blocks. + * @group Extractors */ abstract class UnApplyExtractor { def apply(fun: Tree, args: List[Tree]): UnApply def unapply(unApply: UnApply): Option[(Tree, List[Tree])] } - /** The API that all unapplies support */ + /** The API that all unapplies support + * @group API + */ trait UnApplyApi extends TermTreeApi { this: UnApply => /** A dummy node that carries the type of unapplication. * See the example for [[scala.reflect.api.Trees#UnApplyExtractor]]. @@ -1030,15 +1218,21 @@ trait Trees { self: Universe => val args: List[Tree] } - /** Anonymous function, eliminated by compiler phase lambdalift */ + /** Anonymous function, eliminated by compiler phase lambdalift + * @group Trees + * @template + */ type Function >: Null <: TermTree with SymTree with FunctionApi /** A tag that preserves the identity of the `Function` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val FunctionTag: ClassTag[Function] - /** The constructor/deconstructor for `Function` instances. */ + /** The constructor/deconstructor for `Function` instances. + * @group Extractors + */ val Function: FunctionExtractor /** An extractor class to create and pattern match with syntax `Function(vparams, body)`. @@ -1048,13 +1242,16 @@ trait Trees { self: Universe => * * The symbol of a Function is a synthetic TermSymbol. * It is the owner of the function's parameters. + * @group Extractors */ abstract class FunctionExtractor { def apply(vparams: List[ValDef], body: Tree): Function def unapply(function: Function): Option[(List[ValDef], Tree)] } - /** The API that all functions support */ + /** The API that all functions support + * @group API + */ trait FunctionApi extends TermTreeApi with SymTreeApi { this: Function => /** The list of parameters of the function. */ @@ -1065,28 +1262,37 @@ trait Trees { self: Universe => val body: Tree } - /** Assignment */ + /** Assignment + * @group Trees + * @template + */ type Assign >: Null <: TermTree with AssignApi /** A tag that preserves the identity of the `Assign` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val AssignTag: ClassTag[Assign] - /** The constructor/deconstructor for `Assign` instances. */ + /** The constructor/deconstructor for `Assign` instances. + * @group Extractors + */ val Assign: AssignExtractor /** An extractor class to create and pattern match with syntax `Assign(lhs, rhs)`. * This AST node corresponds to the following Scala code: * * lhs = rhs + * @group Extractors */ abstract class AssignExtractor { def apply(lhs: Tree, rhs: Tree): Assign def unapply(assign: Assign): Option[(Tree, Tree)] } - /** The API that all assigns support */ + /** The API that all assigns support + * @group API + */ trait AssignApi extends TermTreeApi { this: Assign => /** The left-hand side of the assignment. */ @@ -1099,15 +1305,20 @@ trait Trees { self: Universe => /** Either an assignment or a named argument. Only appears in argument lists, * eliminated by compiler phase typecheck (doTypedApply), resurrected by reifier. + * @group Trees + * @template */ type AssignOrNamedArg >: Null <: TermTree with AssignOrNamedArgApi /** A tag that preserves the identity of the `AssignOrNamedArg` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val AssignOrNamedArgTag: ClassTag[AssignOrNamedArg] - /** The constructor/deconstructor for `AssignOrNamedArg` instances. */ + /** The constructor/deconstructor for `AssignOrNamedArg` instances. + * @group Extractors + */ val AssignOrNamedArg: AssignOrNamedArgExtractor /** An extractor class to create and pattern match with syntax `AssignOrNamedArg(lhs, rhs)`. @@ -1120,13 +1331,16 @@ trait Trees { self: Universe => * @annotation(lhs = rhs) * }}} * + * @group Extractors */ abstract class AssignOrNamedArgExtractor { def apply(lhs: Tree, rhs: Tree): AssignOrNamedArg def unapply(assignOrNamedArg: AssignOrNamedArg): Option[(Tree, Tree)] } - /** The API that all assigns support */ + /** The API that all assigns support + * @group API + */ trait AssignOrNamedArgApi extends TermTreeApi { this: AssignOrNamedArg => /** The left-hand side of the expression. */ @@ -1137,15 +1351,21 @@ trait Trees { self: Universe => val rhs: Tree } - /** Conditional expression */ + /** Conditional expression + * @group Trees + * @template + */ type If >: Null <: TermTree with IfApi /** A tag that preserves the identity of the `If` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val IfTag: ClassTag[If] - /** The constructor/deconstructor for `If` instances. */ + /** The constructor/deconstructor for `If` instances. + * @group Extractors + */ val If: IfExtractor /** An extractor class to create and pattern match with syntax `If(cond, thenp, elsep)`. @@ -1154,13 +1374,16 @@ trait Trees { self: Universe => * `if` (cond) thenp `else` elsep * * If the alternative is not present, the `elsep` is set to `Literal(Constant(()))`. + * @group Extractors */ abstract class IfExtractor { def apply(cond: Tree, thenp: Tree, elsep: Tree): If def unapply(if_ : If): Option[(Tree, Tree, Tree)] } - /** The API that all ifs support */ + /** The API that all ifs support + * @group API + */ trait IfApi extends TermTreeApi { this: If => /** The condition of the if. */ @@ -1186,15 +1409,20 @@ trait Trees { self: Universe => * or `Alternative(lit|...|lit)` * - except for an "otherwise" branch, which has pattern * `Ident(nme.WILDCARD)` + * @group Trees + * @template */ type Match >: Null <: TermTree with MatchApi /** A tag that preserves the identity of the `Match` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val MatchTag: ClassTag[Match] - /** The constructor/deconstructor for `Match` instances. */ + /** The constructor/deconstructor for `Match` instances. + * @group Extractors + */ val Match: MatchExtractor /** An extractor class to create and pattern match with syntax `Match(selector, cases)`. @@ -1203,13 +1431,16 @@ trait Trees { self: Universe => * selector `match` { cases } * * `Match` is also used in pattern matching assignments like `val (foo, bar) = baz`. + * @group Extractors */ abstract class MatchExtractor { def apply(selector: Tree, cases: List[CaseDef]): Match def unapply(match_ : Match): Option[(Tree, List[CaseDef])] } - /** The API that all matches support */ + /** The API that all matches support + * @group API + */ trait MatchApi extends TermTreeApi { this: Match => /** The scrutinee of the pattern match. */ val selector: Tree @@ -1218,15 +1449,21 @@ trait Trees { self: Universe => val cases: List[CaseDef] } - /** Return expression */ + /** Return expression + * @group Trees + * @template + */ type Return >: Null <: TermTree with SymTree with ReturnApi /** A tag that preserves the identity of the `Return` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ReturnTag: ClassTag[Return] - /** The constructor/deconstructor for `Return` instances. */ + /** The constructor/deconstructor for `Return` instances. + * @group Extractors + */ val Return: ReturnExtractor /** An extractor class to create and pattern match with syntax `Return(expr)`. @@ -1235,27 +1472,36 @@ trait Trees { self: Universe => * `return` expr * * The symbol of a Return node is the enclosing method. + * @group Extractors */ abstract class ReturnExtractor { def apply(expr: Tree): Return def unapply(return_ : Return): Option[Tree] } - /** The API that all returns support */ + /** The API that all returns support + * @group API + */ trait ReturnApi extends TermTreeApi { this: Return => /** The returned expression. */ val expr: Tree } - /** TODO comment me! */ + /** Try catch node + * @group Trees + * @template + */ type Try >: Null <: TermTree with TryApi /** A tag that preserves the identity of the `Try` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TryTag: ClassTag[Try] - /** The constructor/deconstructor for `Try` instances. */ + /** The constructor/deconstructor for `Try` instances. + * @group Extractors + */ val Try: TryExtractor /** An extractor class to create and pattern match with syntax `Try(block, catches, finalizer)`. @@ -1264,13 +1510,16 @@ trait Trees { self: Universe => * `try` block `catch` { catches } `finally` finalizer * * If the finalizer is not present, the `finalizer` is set to `EmptyTree`. + * @group Extractors */ abstract class TryExtractor { def apply(block: Tree, catches: List[CaseDef], finalizer: Tree): Try def unapply(try_ : Try): Option[(Tree, List[CaseDef], Tree)] } - /** The API that all tries support */ + /** The API that all tries support + * @group API + */ trait TryApi extends TermTreeApi { this: Try => /** The protected block. */ val block: Tree @@ -1282,43 +1531,56 @@ trait Trees { self: Universe => val finalizer: Tree } - /** Throw expression */ + /** Throw expression + * @group Trees + * @template + */ type Throw >: Null <: TermTree with ThrowApi /** A tag that preserves the identity of the `Throw` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ThrowTag: ClassTag[Throw] - /** The constructor/deconstructor for `Throw` instances. */ + /** The constructor/deconstructor for `Throw` instances. + * @group Extractors + */ val Throw: ThrowExtractor /** An extractor class to create and pattern match with syntax `Throw(expr)`. * This AST node corresponds to the following Scala code: * * `throw` expr + * @group Extractors */ abstract class ThrowExtractor { def apply(expr: Tree): Throw def unapply(throw_ : Throw): Option[Tree] } - /** The API that all tries support */ + /** The API that all tries support + * @group API + */ trait ThrowApi extends TermTreeApi { this: Throw => /** The thrown expression. */ val expr: Tree } /** Object instantiation + * @group Trees + * @template */ type New >: Null <: TermTree with NewApi /** A tag that preserves the identity of the `New` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val NewTag: ClassTag[New] /** The constructor/deconstructor for `New` instances. + * @group Extractors */ val New: NewExtractor @@ -1330,6 +1592,7 @@ trait Trees { self: Universe => * This node always occurs in the following context: * * (`new` tpt).[targs](args) + * @group Extractors */ abstract class NewExtractor { /** A user level `new`. @@ -1341,7 +1604,9 @@ trait Trees { self: Universe => def unapply(new_ : New): Option[Tree] } - /** The API that all news support */ + /** The API that all news support + * @group API + */ trait NewApi extends TermTreeApi { this: New => /** The tree that represents the type being instantiated. * See the example for [[scala.reflect.api.Trees#NewExtractor]]. @@ -1349,28 +1614,37 @@ trait Trees { self: Universe => val tpt: Tree } - /** Type annotation, eliminated by compiler phase cleanup */ + /** Type annotation, eliminated by compiler phase cleanup + * @group Trees + * @template + */ type Typed >: Null <: TermTree with TypedApi /** A tag that preserves the identity of the `Typed` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TypedTag: ClassTag[Typed] - /** The constructor/deconstructor for `Typed` instances. */ + /** The constructor/deconstructor for `Typed` instances. + * @group Extractors + */ val Typed: TypedExtractor /** An extractor class to create and pattern match with syntax `Typed(expr, tpt)`. * This AST node corresponds to the following Scala code: * * expr: tpt + * @group Extractors */ abstract class TypedExtractor { def apply(expr: Tree, tpt: Tree): Typed def unapply(typed: Typed): Option[(Tree, Tree)] } - /** The API that all typeds support */ + /** The API that all typeds support + * @group API + */ trait TypedApi extends TermTreeApi { this: Typed => /** The expression being ascribed with the type. */ val expr: Tree @@ -1380,15 +1654,20 @@ trait Trees { self: Universe => } /** Common base class for Apply and TypeApply. + * @group Trees + * @template */ type GenericApply >: Null <: TermTree with GenericApplyApi /** A tag that preserves the identity of the `GenericApply` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val GenericApplyTag: ClassTag[GenericApply] - /** The API that all applies support */ + /** The API that all applies support + * @group API + */ trait GenericApplyApi extends TermTreeApi { this: GenericApply => /** The target of the application. */ val fun: Tree @@ -1401,40 +1680,55 @@ trait Trees { self: Universe => * but I can't find that explicitly stated anywhere. Unless your last name * is odersky, you should probably treat it as true. */ - /** Explicit type application. */ + /** Explicit type application. + * @group Trees + * @template + */ type TypeApply >: Null <: GenericApply with TypeApplyApi /** A tag that preserves the identity of the `TypeApply` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TypeApplyTag: ClassTag[TypeApply] - /** The constructor/deconstructor for `TypeApply` instances. */ + /** The constructor/deconstructor for `TypeApply` instances. + * @group Extractors + */ val TypeApply: TypeApplyExtractor /** An extractor class to create and pattern match with syntax `TypeApply(fun, args)`. * This AST node corresponds to the following Scala code: * * fun[args] + * @group Extractors */ abstract class TypeApplyExtractor { def apply(fun: Tree, args: List[Tree]): TypeApply def unapply(typeApply: TypeApply): Option[(Tree, List[Tree])] } - /** The API that all type applies support */ + /** The API that all type applies support + * @group API + */ trait TypeApplyApi extends GenericApplyApi { this: TypeApply => } - /** Value application */ + /** Value application + * @group Trees + * @template + */ type Apply >: Null <: GenericApply with ApplyApi /** A tag that preserves the identity of the `Apply` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ApplyTag: ClassTag[Apply] - /** The constructor/deconstructor for `Apply` instances. */ + /** The constructor/deconstructor for `Apply` instances. + * @group Extractors + */ val Apply: ApplyExtractor /** An extractor class to create and pattern match with syntax `Apply(fun, args)`. @@ -1449,27 +1743,35 @@ trait Trees { self: Universe => * Is expressed as: * * Apply(TypeApply(fun, targs), args) + * @group Extractors */ abstract class ApplyExtractor { def apply(fun: Tree, args: List[Tree]): Apply def unapply(apply: Apply): Option[(Tree, List[Tree])] } - /** The API that all applies support */ + /** The API that all applies support + * @group API + */ trait ApplyApi extends GenericApplyApi { this: Apply => } /** Super reference, where `qual` is the corresponding `this` reference. * A super reference `C.super[M]` is represented as `Super(This(C), M)`. + * @group Trees + * @template */ type Super >: Null <: TermTree with SuperApi /** A tag that preserves the identity of the `Super` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val SuperTag: ClassTag[Super] - /** The constructor/deconstructor for `Super` instances. */ + /** The constructor/deconstructor for `Super` instances. + * @group Extractors + */ val Super: SuperExtractor /** An extractor class to create and pattern match with syntax `Super(qual, mix)`. @@ -1485,13 +1787,16 @@ trait Trees { self: Universe => * * The symbol of a Super is the class _from_ which the super reference is made. * For instance in C.super(...), it would be C. + * @group Extractors */ abstract class SuperExtractor { def apply(qual: Tree, mix: TypeName): Super def unapply(super_ : Super): Option[(Tree, TypeName)] } - /** The API that all supers support */ + /** The API that all supers support + * @group API + */ trait SuperApi extends TermTreeApi { this: Super => /** The qualifier of the `super` expression. * See the example for [[scala.reflect.api.Trees#SuperExtractor]]. @@ -1504,15 +1809,21 @@ trait Trees { self: Universe => val mix: TypeName } - /** Self reference */ + /** Self reference + * @group Trees + * @template + */ type This >: Null <: TermTree with SymTree with ThisApi /** A tag that preserves the identity of the `This` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ThisTag: ClassTag[This] - /** The constructor/deconstructor for `This` instances. */ + /** The constructor/deconstructor for `This` instances. + * @group Extractors + */ val This: ThisExtractor /** An extractor class to create and pattern match with syntax `This(qual)`. @@ -1522,13 +1833,16 @@ trait Trees { self: Universe => * * The symbol of a This is the class to which the this refers. * For instance in C.this, it would be C. + * @group Extractors */ abstract class ThisExtractor { def apply(qual: TypeName): This def unapply(this_ : This): Option[TypeName] } - /** The API that all thises support */ + /** The API that all thises support + * @group API + */ trait ThisApi extends TermTreeApi with SymTreeApi { this: This => /** The qualifier of the `this` expression. * For an unqualified `this` refers to the enclosing class. @@ -1536,28 +1850,37 @@ trait Trees { self: Universe => val qual: TypeName } - /** A member selection . */ + /** A member selection . + * @group Trees + * @template + */ type Select >: Null <: RefTree with SelectApi /** A tag that preserves the identity of the `Select` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val SelectTag: ClassTag[Select] - /** The constructor/deconstructor for `Select` instances. */ + /** The constructor/deconstructor for `Select` instances. + * @group Extractors + */ val Select: SelectExtractor /** An extractor class to create and pattern match with syntax `Select(qual, name)`. * This AST node corresponds to the following Scala code: * * qualifier.selector + * @group Extractors */ abstract class SelectExtractor { def apply(qualifier: Tree, name: Name): Select def unapply(select: Select): Option[(Tree, Name)] } - /** The API that all selects support */ + /** The API that all selects support + * @group API + */ trait SelectApi extends RefTreeApi { this: Select => /** @inheritdoc */ val qualifier: Tree @@ -1567,15 +1890,20 @@ trait Trees { self: Universe => } /** A reference to identifier `name`. + * @group Trees + * @template */ type Ident >: Null <: RefTree with IdentApi /** A tag that preserves the identity of the `Ident` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val IdentTag: ClassTag[Ident] - /** The constructor/deconstructor for `Ident` instances. */ + /** The constructor/deconstructor for `Ident` instances. + * @group Extractors + */ val Ident: IdentExtractor /** An extractor class to create and pattern match with syntax `Ident(qual, name)`. @@ -1585,33 +1913,42 @@ trait Trees { self: Universe => * * Type checker converts idents that refer to enclosing fields or methods to selects. * For example, name ==> this.name + * @group Extractors */ abstract class IdentExtractor { def apply(name: Name): Ident def unapply(ident: Ident): Option[Name] } - /** The API that all idents support */ + /** The API that all idents support + * @group API + */ trait IdentApi extends RefTreeApi { this: Ident => /** @inheritdoc */ val name: Name } /** Marks underlying reference to id as boxed. - * @pre id must refer to a captured variable + * + * Precondition:<\b> id must refer to a captured variable * A reference such marked will refer to the boxed entity, no dereferencing * with `.elem` is done on it. * This tree node can be emitted by macros such as reify that call referenceCapturedVariable. * It is eliminated in LambdaLift, where the boxing conversion takes place. + * @group Trees + * @template */ type ReferenceToBoxed >: Null <: TermTree with ReferenceToBoxedApi /** A tag that preserves the identity of the `ReferenceToBoxed` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ReferenceToBoxedTag: ClassTag[ReferenceToBoxed] - /** The constructor/deconstructor for `ReferenceToBoxed` instances. */ + /** The constructor/deconstructor for `ReferenceToBoxed` instances. + * @group Extractors + */ val ReferenceToBoxed: ReferenceToBoxedExtractor /** An extractor class to create and pattern match with syntax `ReferenceToBoxed(ident)`. @@ -1632,40 +1969,52 @@ trait Trees { self: Universe => * Select(Ident(x), "elem") * * If `ReferenceToBoxed` were used instead of Ident, no transformation would be performed. + * @group Extractors */ abstract class ReferenceToBoxedExtractor { def apply(ident: Ident): ReferenceToBoxed def unapply(referenceToBoxed: ReferenceToBoxed): Option[Ident] } - /** The API that all references support */ + /** The API that all references support + * @group API + */ trait ReferenceToBoxedApi extends TermTreeApi { this: ReferenceToBoxed => /** The underlying reference. */ val ident: Tree } - /** Literal */ + /** Literal + * @group Trees + * @template + */ type Literal >: Null <: TermTree with LiteralApi /** A tag that preserves the identity of the `Literal` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val LiteralTag: ClassTag[Literal] - /** The constructor/deconstructor for `Literal` instances. */ + /** The constructor/deconstructor for `Literal` instances. + * @group Extractors + */ val Literal: LiteralExtractor /** An extractor class to create and pattern match with syntax `Literal(value)`. * This AST node corresponds to the following Scala code: * * value + * @group Extractors */ abstract class LiteralExtractor { def apply(value: Constant): Literal def unapply(literal: Literal): Option[Constant] } - /** The API that all literals support */ + /** The API that all literals support + * @group API + */ trait LiteralApi extends TermTreeApi { this: Literal => /** The compile-time constant underlying the literal. */ val value: Constant @@ -1675,15 +2024,20 @@ trait Trees { self: Universe => * annotation ascriptions, annotations on definitions are stored in the Modifiers. * Eliminated by typechecker (typedAnnotated), the annotations are then stored in * an AnnotatedType. + * @group Trees + * @template */ type Annotated >: Null <: AnyRef with Tree with AnnotatedApi /** A tag that preserves the identity of the `Annotated` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val AnnotatedTag: ClassTag[Annotated] - /** The constructor/deconstructor for `Annotated` instances. */ + /** The constructor/deconstructor for `Annotated` instances. + * @group Extractors + */ val Annotated: AnnotatedExtractor /** An extractor class to create and pattern match with syntax `Annotated(annot, arg)`. @@ -1691,13 +2045,16 @@ trait Trees { self: Universe => * * arg @annot // for types * arg: @annot // for exprs + * @group Extractors */ abstract class AnnotatedExtractor { def apply(annot: Tree, arg: Tree): Annotated def unapply(annotated: Annotated): Option[(Tree, Tree)] } - /** The API that all annotateds support */ + /** The API that all annotateds support + * @group API + */ trait AnnotatedApi extends TreeApi { this: Annotated => /** The annotation. */ val annot: Tree @@ -1706,43 +2063,58 @@ trait Trees { self: Universe => val arg: Tree } - /** Singleton type, eliminated by RefCheck */ + /** Singleton type, eliminated by RefCheck + * @group Trees + * @template + */ type SingletonTypeTree >: Null <: TypTree with SingletonTypeTreeApi /** A tag that preserves the identity of the `SingletonTypeTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val SingletonTypeTreeTag: ClassTag[SingletonTypeTree] - /** The constructor/deconstructor for `SingletonTypeTree` instances. */ + /** The constructor/deconstructor for `SingletonTypeTree` instances. + * @group Extractors + */ val SingletonTypeTree: SingletonTypeTreeExtractor /** An extractor class to create and pattern match with syntax `SingletonTypeTree(ref)`. * This AST node corresponds to the following Scala code: * * ref.type + * @group Extractors */ abstract class SingletonTypeTreeExtractor { def apply(ref: Tree): SingletonTypeTree def unapply(singletonTypeTree: SingletonTypeTree): Option[Tree] } - /** The API that all singleton type trees support */ + /** The API that all singleton type trees support + * @group API + */ trait SingletonTypeTreeApi extends TypTreeApi { this: SingletonTypeTree => /** The underlying reference. */ val ref: Tree } - /** Type selection # , eliminated by RefCheck */ + /** Type selection # , eliminated by RefCheck + * @group Trees + * @template + */ // [Eugene++] don't see why we need it, when we have Select type SelectFromTypeTree >: Null <: TypTree with RefTree with SelectFromTypeTreeApi /** A tag that preserves the identity of the `SelectFromTypeTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val SelectFromTypeTreeTag: ClassTag[SelectFromTypeTree] - /** The constructor/deconstructor for `SelectFromTypeTree` instances. */ + /** The constructor/deconstructor for `SelectFromTypeTree` instances. + * @group Extractors + */ val SelectFromTypeTree: SelectFromTypeTreeExtractor /** An extractor class to create and pattern match with syntax `SelectFromTypeTree(qualifier, name)`. @@ -1751,13 +2123,16 @@ trait Trees { self: Universe => * qualifier # selector * * Note: a path-dependent type p.T is expressed as p.type # T + * @group Extractors */ abstract class SelectFromTypeTreeExtractor { def apply(qualifier: Tree, name: TypeName): SelectFromTypeTree def unapply(selectFromTypeTree: SelectFromTypeTree): Option[(Tree, TypeName)] } - /** The API that all selects from type trees support */ + /** The API that all selects from type trees support + * @group API + */ trait SelectFromTypeTreeApi extends TypTreeApi with RefTreeApi { this: SelectFromTypeTree => /** @inheritdoc */ val qualifier: Tree @@ -1766,55 +2141,73 @@ trait Trees { self: Universe => val name: TypeName } - /** Intersection type with ... with { }, eliminated by RefCheck */ + /** Intersection type with ... with { }, eliminated by RefCheck + * @group Trees + * @template + */ type CompoundTypeTree >: Null <: TypTree with CompoundTypeTreeApi /** A tag that preserves the identity of the `CompoundTypeTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val CompoundTypeTreeTag: ClassTag[CompoundTypeTree] - /** The constructor/deconstructor for `CompoundTypeTree` instances. */ + /** The constructor/deconstructor for `CompoundTypeTree` instances. + * @group Extractors + */ val CompoundTypeTree: CompoundTypeTreeExtractor /** An extractor class to create and pattern match with syntax `CompoundTypeTree(templ)`. * This AST node corresponds to the following Scala code: * * parent1 with ... with parentN { refinement } + * @group Extractors */ abstract class CompoundTypeTreeExtractor { def apply(templ: Template): CompoundTypeTree def unapply(compoundTypeTree: CompoundTypeTree): Option[Template] } - /** The API that all compound type trees support */ + /** The API that all compound type trees support + * @group API + */ trait CompoundTypeTreeApi extends TypTreeApi { this: CompoundTypeTree => /** The template of the compound type - represents the parents, the optional self-type and the optional definitions. */ val templ: Template } - /** Applied type [ ], eliminated by RefCheck */ + /** Applied type [ ], eliminated by RefCheck + * @group Trees + * @template + */ type AppliedTypeTree >: Null <: TypTree with AppliedTypeTreeApi /** A tag that preserves the identity of the `AppliedTypeTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val AppliedTypeTreeTag: ClassTag[AppliedTypeTree] - /** The constructor/deconstructor for `AppliedTypeTree` instances. */ + /** The constructor/deconstructor for `AppliedTypeTree` instances. + * @group Extractors + */ val AppliedTypeTree: AppliedTypeTreeExtractor /** An extractor class to create and pattern match with syntax `AppliedTypeTree(tpt, args)`. * This AST node corresponds to the following Scala code: * * tpt[args] + * @group Extractors */ abstract class AppliedTypeTreeExtractor { def apply(tpt: Tree, args: List[Tree]): AppliedTypeTree def unapply(appliedTypeTree: AppliedTypeTree): Option[(Tree, List[Tree])] } - /** The API that all applied type trees support */ + /** The API that all applied type trees support + * @group API + */ trait AppliedTypeTreeApi extends TypTreeApi { this: AppliedTypeTree => /** The target of the application. */ val tpt: Tree @@ -1823,28 +2216,37 @@ trait Trees { self: Universe => val args: List[Tree] } - /** Document me! */ + /** Type bounds tree node + * @group Trees + * @template + */ type TypeBoundsTree >: Null <: TypTree with TypeBoundsTreeApi /** A tag that preserves the identity of the `TypeBoundsTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TypeBoundsTreeTag: ClassTag[TypeBoundsTree] - /** The constructor/deconstructor for `TypeBoundsTree` instances. */ + /** The constructor/deconstructor for `TypeBoundsTree` instances. + * @group Extractors + */ val TypeBoundsTree: TypeBoundsTreeExtractor /** An extractor class to create and pattern match with syntax `TypeBoundsTree(lo, hi)`. * This AST node corresponds to the following Scala code: * * >: lo <: hi + * @group Extractors */ abstract class TypeBoundsTreeExtractor { def apply(lo: Tree, hi: Tree): TypeBoundsTree def unapply(typeBoundsTree: TypeBoundsTree): Option[(Tree, Tree)] } - /** The API that all type bound trees support */ + /** The API that all type bound trees support + * @group API + */ trait TypeBoundsTreeApi extends TypTreeApi { this: TypeBoundsTree => /** The lower bound. * Is equal to `Ident()` if not specified explicitly. @@ -1857,28 +2259,37 @@ trait Trees { self: Universe => val hi: Tree } - /** TODO Document me! */ + /** Existential type tree node + * @group Trees + * @template + */ type ExistentialTypeTree >: Null <: TypTree with ExistentialTypeTreeApi /** A tag that preserves the identity of the `ExistentialTypeTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ExistentialTypeTreeTag: ClassTag[ExistentialTypeTree] - /** The constructor/deconstructor for `ExistentialTypeTree` instances. */ + /** The constructor/deconstructor for `ExistentialTypeTree` instances. + * @group Extractors + */ val ExistentialTypeTree: ExistentialTypeTreeExtractor /** An extractor class to create and pattern match with syntax `ExistentialTypeTree(tpt, whereClauses)`. * This AST node corresponds to the following Scala code: * * tpt forSome { whereClauses } + * @group Extractors */ abstract class ExistentialTypeTreeExtractor { def apply(tpt: Tree, whereClauses: List[Tree]): ExistentialTypeTree def unapply(existentialTypeTree: ExistentialTypeTree): Option[(Tree, List[Tree])] } - /** The API that all existential type trees support */ + /** The API that all existential type trees support + * @group API + */ trait ExistentialTypeTreeApi extends TypTreeApi { this: ExistentialTypeTree => /** The underlying type of the existential type. */ val tpt: Tree @@ -1888,30 +2299,39 @@ trait Trees { self: Universe => } /** A synthetic tree holding an arbitrary type. Not to be confused with - * with TypTree, the trait for trees that are only used for type trees. - * TypeTree's are inserted in several places, but most notably in - * `RefCheck`, where the arbitrary type trees are all replaced by - * TypeTree's. */ + * with TypTree, the trait for trees that are only used for type trees. + * TypeTree's are inserted in several places, but most notably in + * `RefCheck`, where the arbitrary type trees are all replaced by + * TypeTree's. + * @group Trees + * @template + */ type TypeTree >: Null <: TypTree with TypeTreeApi /** A tag that preserves the identity of the `TypeTree` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TypeTreeTag: ClassTag[TypeTree] - /** The constructor/deconstructor for `TypeTree` instances. */ + /** The constructor/deconstructor for `TypeTree` instances. + * @group Extractors + */ val TypeTree: TypeTreeExtractor /** An extractor class to create and pattern match with syntax `TypeTree()`. * This AST node does not have direct correspondence to Scala code, * and is emitted by everywhere when we want to wrap a `Type` in a `Tree`. + * @group Extractors */ abstract class TypeTreeExtractor { def apply(): TypeTree def unapply(typeTree: TypeTree): Boolean } - /** The API that all type trees support */ + /** The API that all type trees support + * @group API + */ trait TypeTreeApi extends TypTreeApi { this: TypeTree => /** The precursor of this tree. * Is equal to `EmptyTree` if this type tree doesn't have precursors. @@ -1923,149 +2343,185 @@ trait Trees { self: Universe => * val _: _ * This is used as a placeholder in the `self` parameter Template if there is * no definition of a self value of self type. + * @group Trees */ val emptyValDef: ValDef // ---------------------- factories ---------------------------------------------- /** A factory method for `ClassDef` nodes. + * @group Factories */ def ClassDef(sym: Symbol, impl: Template): ClassDef /** A factory method for `ModuleDef` nodes. + * @group Factories */ def ModuleDef(sym: Symbol, impl: Template): ModuleDef /** A factory method for `ValDef` nodes. + * @group Factories */ def ValDef(sym: Symbol, rhs: Tree): ValDef /** A factory method for `ValDef` nodes. + * @group Factories */ def ValDef(sym: Symbol): ValDef /** A factory method for `ValDef` nodes. + * @group Factories */ def DefDef(sym: Symbol, mods: Modifiers, vparamss: List[List[ValDef]], rhs: Tree): DefDef /** A factory method for `ValDef` nodes. + * @group Factories */ def DefDef(sym: Symbol, vparamss: List[List[ValDef]], rhs: Tree): DefDef /** A factory method for `ValDef` nodes. + * @group Factories */ def DefDef(sym: Symbol, mods: Modifiers, rhs: Tree): DefDef /** A factory method for `ValDef` nodes. + * @group Factories */ def DefDef(sym: Symbol, rhs: Tree): DefDef /** A factory method for `ValDef` nodes. + * @group Factories */ def DefDef(sym: Symbol, rhs: List[List[Symbol]] => Tree): DefDef /** A factory method for `TypeDef` nodes. + * @group Factories */ def TypeDef(sym: Symbol, rhs: Tree): TypeDef /** A factory method for `TypeDef` nodes. + * @group Factories */ def TypeDef(sym: Symbol): TypeDef /** A factory method for `LabelDef` nodes. + * @group Factories */ def LabelDef(sym: Symbol, params: List[Symbol], rhs: Tree): LabelDef /** A factory method for `Block` nodes. * Flattens directly nested blocks. + * @group Factories */ def Block(stats: Tree*): Block /** A factory method for `CaseDef` nodes. + * @group Factories */ def CaseDef(pat: Tree, body: Tree): CaseDef /** A factory method for `Bind` nodes. + * @group Factories */ def Bind(sym: Symbol, body: Tree): Bind /** A factory method for `Try` nodes. + * @group Factories */ def Try(body: Tree, cases: (Tree, Tree)*): Try /** A factory method for `Throw` nodes. + * @group Factories */ def Throw(tpe: Type, args: Tree*): Throw /** Factory method for object creation `new tpt(args_1)...(args_n)` * A `New(t, as)` is expanded to: `(new t).(as)` + * @group Factories */ def New(tpt: Tree, argss: List[List[Tree]]): Tree /** 0-1 argument list new, based on a type. + * @group Factories */ def New(tpe: Type, args: Tree*): Tree /** 0-1 argument list new, based on a symbol. + * @group Factories */ def New(sym: Symbol, args: Tree*): Tree /** A factory method for `Apply` nodes. + * @group Factories */ def Apply(sym: Symbol, args: Tree*): Tree /** 0-1 argument list new, based on a type tree. + * @group Factories */ def ApplyConstructor(tpt: Tree, args: List[Tree]): Tree /** A factory method for `Super` nodes. + * @group Factories */ def Super(sym: Symbol, mix: TypeName): Tree /** A factory method for `This` nodes. + * @group Factories */ def This(sym: Symbol): Tree /** A factory method for `Select` nodes. - * The string `name` argument is assumed to represent a [[scala.reflect.api.Names#TermName]. + * The string `name` argument is assumed to represent a [[scala.reflect.api.Names#TermName `TermName`]]. + * @group Factories */ def Select(qualifier: Tree, name: String): Select /** A factory method for `Select` nodes. + * @group Factories */ def Select(qualifier: Tree, sym: Symbol): Select /** A factory method for `Ident` nodes. + * @group Factories */ def Ident(name: String): Ident /** A factory method for `Ident` nodes. + * @group Factories */ def Ident(sym: Symbol): Ident /** A factory method for `TypeTree` nodes. + * @group Factories */ def TypeTree(tp: Type): TypeTree // ---------------------- copying ------------------------------------------------ /** The type of standard (lazy) tree copiers. + * @template + * @group Copying */ type TreeCopier <: TreeCopierOps /** The standard (lazy) tree copier. + * @group Copying */ val treeCopy: TreeCopier = newLazyTreeCopier /** Creates a strict tree copier. + * @group Copying */ def newStrictTreeCopier: TreeCopier /** Creates a lazy tree copier. + * @group Copying */ def newLazyTreeCopier: TreeCopier /** The API of a tree copier. + * @group API */ abstract class TreeCopierOps { /** Creates a `ClassDef` node from the given components, having a given `tree` as a prototype. @@ -2277,6 +2733,7 @@ trait Trees { self: Universe => // ---------------------- traversing and transforming ------------------------------ /** A class that implement a default tree traversal strategy: breadth-first component-wise. + * @group Traversal */ class Traverser { protected[scala] var currentOwner: Symbol = rootMirror.RootClass @@ -2315,17 +2772,20 @@ trait Trees { self: Universe => def apply[T <: Tree](tree: T): T = { traverse(tree); tree } } - /** Delegates the traversal strategy to [[scala.reflect.internal.Trees]], + /** Delegates the traversal strategy to `scala.reflect.internal.Trees`, * because pattern matching on abstract types we have here degrades performance. + * @group Traversal */ protected def itraverse(traverser: Traverser, tree: Tree): Unit = throw new MatchError(tree) /** Provides an extension hook for the traversal strategy. * Future-proofs against new node types. + * @group Traversal */ protected def xtraverse(traverser: Traverser, tree: Tree): Unit = throw new MatchError(tree) /** A class that implement a default tree transformation strategy: breadth-first component-wise cloning. + * @group Traversal */ abstract class Transformer { /** The underlying tree copier. */ @@ -2396,25 +2856,32 @@ trait Trees { self: Universe => } } - /** Delegates the transformation strategy to [[scala.reflect.internal.Trees]], + /** Delegates the transformation strategy to `scala.reflect.internal.Trees`, * because pattern matching on abstract types we have here degrades performance. + * @group Traversal */ protected def itransform(transformer: Transformer, tree: Tree): Tree = throw new MatchError(tree) /** Provides an extension hook for the transformation strategy. * Future-proofs against new node types. + * @group Traversal */ protected def xtransform(transformer: Transformer, tree: Tree): Tree = throw new MatchError(tree) - /** The type of tree modifiers. */ + /** The type of tree modifiers. + * @group Traversal + */ type Modifiers >: Null <: AnyRef with ModifiersApi /** A tag that preserves the identity of the `Modifiers` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Traversal */ implicit val ModifiersTag: ClassTag[Modifiers] - /** The API that all Modifiers support */ + /** The API that all Modifiers support + * @group API + */ abstract class ModifiersApi { /** The underlying flags of the enclosing definition. * Is equal to `NoFlags` if none are specified explicitly. @@ -2440,23 +2907,32 @@ trait Trees { self: Universe => Modifiers(flags, privateWithin, f(annotations)) } - /** The constructor/deconstructor for `Modifiers` instances. */ + /** The constructor/deconstructor for `Modifiers` instances. + * @group Traversal + */ val Modifiers: ModifiersCreator /** An extractor class to create and pattern match with syntax `Modifiers(flags, privateWithin, annotations)`. * Modifiers encapsulate flags, visibility annotations and Scala annotations for member definitions. + * @group Traversal */ abstract class ModifiersCreator { def apply(): Modifiers = Modifiers(NoFlags, tpnme.EMPTY, List()) def apply(flags: FlagSet, privateWithin: Name, annotations: List[Tree]): Modifiers } - /** The factory for `Modifiers` instances. */ + /** The factory for `Modifiers` instances. + * @group Traversal + */ def Modifiers(flags: FlagSet, privateWithin: Name): Modifiers = Modifiers(flags, privateWithin, List()) - /** The factory for `Modifiers` instances. */ + /** The factory for `Modifiers` instances. + * @group Traversal + */ def Modifiers(flags: FlagSet): Modifiers = Modifiers(flags, tpnme.EMPTY) - /** An empty `Modifiers` object: no flags, empty visibility annotation and no Scala annotations. */ + /** An empty `Modifiers` object: no flags, empty visibility annotation and no Scala annotations. + * @group Traversal + */ lazy val NoMods = Modifiers() } diff --git a/src/reflect/scala/reflect/api/TypeTags.scala b/src/reflect/scala/reflect/api/TypeTags.scala index 0b1d3b8172..9d66a9e236 100644 --- a/src/reflect/scala/reflect/api/TypeTags.scala +++ b/src/reflect/scala/reflect/api/TypeTags.scala @@ -58,14 +58,14 @@ import scala.language.implicitConversions * TypeTag allows unbound type arguments for which type tags are available: * {{{ * scala> def foo3[T:TypeTag] = firstTypeArg( implicitly[TypeTag[Container[T]]] ) - * foo3: [T](implicit evidence$1: reflect.runtime.universe.TypeTag[T])reflect.runtime.universe.Type + * foo3: [T](implicit evidence\$1: reflect.runtime.universe.TypeTag[T])reflect.runtime.universe.Type * scala> foo3[Person] * res1: reflect.runtime.universe.Type = Person * }}} * WeakTypeTag contains concrete type arguments if available via existing tags: * {{{ * scala> def foo4[T:WeakTypeTag] = firstTypeArg( implicitly[WeakTypeTag[Container[T]]] ) - * foo4: [T](implicit evidence$1: reflect.runtime.universe.WeakTypeTag[T])reflect.runtime.universe.Type + * foo4: [T](implicit evidence\$1: reflect.runtime.universe.WeakTypeTag[T])reflect.runtime.universe.Type * scala> foo4[Person] * res1: reflect.runtime.universe.Type = Person * }}} @@ -141,6 +141,7 @@ import scala.language.implicitConversions * has been created to track the implementation of this feature. * * @see [[scala.reflect.ClassTag]], [[scala.reflect.api.Universe#TypeTag]], [[scala.reflect.api.Universe#WeakTypeTag]] + * @group TypeTags Type Tags */ trait TypeTags { self: Universe => @@ -157,6 +158,7 @@ trait TypeTags { self: Universe => * [[scala.reflect.api.Universe#TypeTag]] instead, which statically guarantees this property. * * @see [[scala.reflect.api.TypeTags]] + * @group TypeTags */ @annotation.implicitNotFound(msg = "No WeakTypeTag available for ${T}") trait WeakTypeTag[T] extends Equals with Serializable { @@ -193,6 +195,7 @@ trait TypeTags { self: Universe => /** * Type tags corresponding to primitive types and constructor/extractor for WeakTypeTags. + * @group TypeTags */ object WeakTypeTag { val Byte : WeakTypeTag[scala.Byte] = TypeTag.Byte @@ -235,6 +238,7 @@ trait TypeTags { self: Universe => def unapply[T](ttag: WeakTypeTag[T]): Option[Type] = Some(ttag.tpe) } + /* @group TypeTags */ private class WeakTypeTagImpl[T](val mirror: Mirror, val tpec: TypeCreator) extends WeakTypeTag[T] { lazy val tpe: Type = tpec(mirror) def in[U <: Universe with Singleton](otherMirror: scala.reflect.api.Mirror[U]): U # WeakTypeTag[T] = { @@ -250,6 +254,7 @@ trait TypeTags { self: Universe => * unresolved type parameters or abstract types. * * @see [[scala.reflect.api.TypeTags]] + * @group TypeTags */ @annotation.implicitNotFound(msg = "No TypeTag available for ${T}") trait TypeTag[T] extends WeakTypeTag[T] with Equals with Serializable { @@ -273,6 +278,7 @@ trait TypeTags { self: Universe => /** * Type tags corresponding to primitive types and constructor/extractor for WeakTypeTags. + * @group TypeTags */ object TypeTag { val Byte: TypeTag[scala.Byte] = new PredefTypeTag[scala.Byte] (ByteTpe, _.TypeTag.Byte) @@ -314,6 +320,7 @@ trait TypeTags { self: Universe => def unapply[T](ttag: TypeTag[T]): Option[Type] = Some(ttag.tpe) } + /* @group TypeTags */ private class TypeTagImpl[T](mirror: Mirror, tpec: TypeCreator) extends WeakTypeTagImpl[T](mirror, tpec) with TypeTag[T] { override def in[U <: Universe with Singleton](otherMirror: scala.reflect.api.Mirror[U]): U # TypeTag[T] = { val otherMirror1 = otherMirror.asInstanceOf[scala.reflect.api.Mirror[otherMirror.universe.type]] @@ -322,12 +329,14 @@ trait TypeTags { self: Universe => private def writeReplace(): AnyRef = new SerializedTypeTag(tpec, concrete = true) } + /* @group TypeTags */ private class PredefTypeCreator[T](copyIn: Universe => Universe#TypeTag[T]) extends TypeCreator { def apply[U <: Universe with Singleton](m: scala.reflect.api.Mirror[U]): U # Type = { copyIn(m.universe).asInstanceOf[U # TypeTag[T]].tpe } } + /* @group TypeTags */ private class PredefTypeTag[T](_tpe: Type, copyIn: Universe => Universe#TypeTag[T]) extends TypeTagImpl[T](rootMirror, new PredefTypeCreator(copyIn)) { override lazy val tpe: Type = _tpe private def writeReplace(): AnyRef = new SerializedTypeTag(tpec, concrete = true) @@ -335,22 +344,26 @@ trait TypeTags { self: Universe => /** * Shortcut for `implicitly[WeakTypeTag[T]]` + * @group TypeTags */ def weakTypeTag[T](implicit attag: WeakTypeTag[T]) = attag /** * Shortcut for `implicitly[TypeTag[T]]` + * @group TypeTags */ def typeTag[T](implicit ttag: TypeTag[T]) = ttag // big thanks to Viktor Klang for this brilliant idea! /** * Shortcut for `implicitly[WeakTypeTag[T]].tpe` + * @group TypeTags */ def weakTypeOf[T](implicit attag: WeakTypeTag[T]): Type = attag.tpe /** * Shortcut for `implicitly[TypeTag[T]].tpe` + * @group TypeTags */ def typeOf[T](implicit ttag: TypeTag[T]): Type = ttag.tpe } diff --git a/src/reflect/scala/reflect/api/Types.scala b/src/reflect/scala/reflect/api/Types.scala index 164dd2c50d..f4760cf088 100644 --- a/src/reflect/scala/reflect/api/Types.scala +++ b/src/reflect/scala/reflect/api/Types.scala @@ -3,8 +3,8 @@ 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, + * 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. * * === Instantiating types === @@ -12,11 +12,11 @@ package api * 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. + * 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.TypeTag#TypeTag]] + * `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. * * Finally, types can be instantiated manually using factory methods such as `typeRef` or `polyType`. @@ -28,15 +28,15 @@ package api * * Common operations on types are querying them for inner declarations or type conformance tests. * - * 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 + * 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` * - * 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 + * 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. * - * The vanilla `==` method should not be used to compare types for equality. Instead, one should always use the `=:=` method. + * 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[_]]`. * * === Exploring types === @@ -52,8 +52,8 @@ package api * 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> 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 @@ -62,31 +62,39 @@ package api * res1 @ 10139edf: String = I've been called for an x typed as List[Any] * }}} * + * @groupname TypeCreators Types - Creation + * @groupname TypeOps Types - Operations */ trait Types { self: Universe => /** The type of Scala types, and also Scala type signatures. * (No difference is internally made between the two). + * @template + * @group Types */ type Type >: Null <: TypeApi /** A tag that preserves the identity of the `Type` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TypeTagg: ClassTag[Type] /** This constant is used as a special value that indicates that no meaningful type exists. + * @group Types */ val NoType: Type /** This constant is used as a special value denoting the empty prefix in a path dependent type. * For instance `x.type` is represented as `SingleType(NoPrefix, )`, where `` stands for * the symbol for `x`. + * @group Types */ val NoPrefix: Type /** The API of types. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ abstract class TypeApi { /** The term symbol associated with the type, or `NoSymbol` for types @@ -242,11 +250,14 @@ trait Types { self: Universe => * x.type * }}} * as well as [[ConstantType constant types]]. + * @template + * @group Types */ type SingletonType >: Null <: Type /** A tag that preserves the identity of the `SingletonType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val SingletonTypeTag: ClassTag[SingletonType] @@ -255,19 +266,25 @@ trait Types { self: Universe => * {{{ * C.this.type ThisType(C) * }}} + * @template + * @group Types */ type ThisType >: Null <: AnyRef with SingletonType with ThisTypeApi /** A tag that preserves the identity of the `ThisType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ThisTypeTag: ClassTag[ThisType] - /** The constructor/deconstructor for `ThisType` instances. */ + /** The constructor/deconstructor for `ThisType` instances. + * @group Extractors + */ val ThisType: ThisTypeExtractor /** An extractor class to create and pattern match with syntax `ThisType(sym)` * where `sym` is the class prefix of the this type. + * @group Extractors */ abstract class ThisTypeExtractor { /** @@ -279,6 +296,7 @@ trait Types { self: Universe => /** The API that all this types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait ThisTypeApi extends TypeApi { this: ThisType => /** The underlying class symbol. */ @@ -292,20 +310,26 @@ trait Types { self: Universe => * p.x.type SingleType(p.type, x) * x.type SingleType(NoPrefix, x) * }}} + * @template + * @group Types */ type SingleType >: Null <: AnyRef with SingletonType with SingleTypeApi /** A tag that preserves the identity of the `SingleType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val SingleTypeTag: ClassTag[SingleType] - /** The constructor/deconstructor for `SingleType` instances. */ + /** The constructor/deconstructor for `SingleType` instances. + * @group Extractors + */ val SingleType: SingleTypeExtractor /** An extractor class to create and pattern match with syntax `SingleType(pre, sym)` * Here, `pre` is the prefix of the single-type, and `sym` is the stable value symbol * referred to by the single-type. + * @group Extractors */ abstract class SingleTypeExtractor { def apply(pre: Type, sym: Symbol): Type // not SingleTypebecause of implementation details @@ -314,6 +338,7 @@ trait Types { self: Universe => /** The API that all single types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait SingleTypeApi extends TypeApi { this: SingleType => /** The type of the qualifier. */ @@ -330,18 +355,24 @@ trait Types { self: Universe => * Here, `thistpe` is the type of the corresponding this-type. For instance, * in the type arising from C.super, the `thistpe` part would be `ThisType(C)`. * `supertpe` is the type of the super class referred to by the `super`. + * @template + * @group Types */ type SuperType >: Null <: AnyRef with SingletonType with SuperTypeApi /** A tag that preserves the identity of the `SuperType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val SuperTypeTag: ClassTag[SuperType] - /** The constructor/deconstructor for `SuperType` instances. */ + /** The constructor/deconstructor for `SuperType` instances. + * @group Extractors + */ val SuperType: SuperTypeExtractor /** An extractor class to create and pattern match with syntax `SingleType(thistpe, supertpe)` + * @group Extractors */ abstract class SuperTypeExtractor { def apply(thistpe: Type, supertpe: Type): Type // not SuperTypebecause of implementation details @@ -350,6 +381,7 @@ trait Types { self: Universe => /** The API that all super types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait SuperTypeApi extends TypeApi { this: SuperType => /** The type of the qualifier. @@ -368,19 +400,25 @@ trait Types { self: Universe => * 1 ConstantType(Constant(1)) * "abc" ConstantType(Constant("abc")) * }}} + * @template + * @group Types */ type ConstantType >: Null <: AnyRef with SingletonType with ConstantTypeApi /** A tag that preserves the identity of the `ConstantType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ConstantTypeTag: ClassTag[ConstantType] - /** The constructor/deconstructor for `ConstantType` instances. */ + /** The constructor/deconstructor for `ConstantType` instances. + * @group Extractors + */ val ConstantType: ConstantTypeExtractor /** An extractor class to create and pattern match with syntax `ConstantType(constant)` * Here, `constant` is the constant value represented by the type. + * @group Extractors */ abstract class ConstantTypeExtractor { def apply(value: Constant): ConstantType @@ -389,6 +427,7 @@ trait Types { self: Universe => /** The API that all constant types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait ConstantTypeApi extends TypeApi { this: ConstantType => /** The compile-time constant underlying this type. */ @@ -405,21 +444,27 @@ trait Types { self: Universe => * p.C TypeRef(p.type, C, Nil) * C TypeRef(NoPrefix, C, Nil) * }}} + * @template + * @group Types */ type TypeRef >: Null <: AnyRef with Type with TypeRefApi /** A tag that preserves the identity of the `TypeRef` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TypeRefTag: ClassTag[TypeRef] - /** The constructor/deconstructor for `TypeRef` instances. */ + /** The constructor/deconstructor for `TypeRef` instances. + * @group Extractors + */ val TypeRef: TypeRefExtractor /** An extractor class to create and pattern match with syntax `TypeRef(pre, sym, args)` * Here, `pre` is the prefix of the type reference, `sym` is the symbol * referred to by the type reference, and `args` is a possible empty list of * type argumenrts. + * @group Extractors */ abstract class TypeRefExtractor { def apply(pre: Type, sym: Symbol, args: List[Type]): Type // not TypeRefbecause of implementation details @@ -428,6 +473,7 @@ trait Types { self: Universe => /** The API that all type refs support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait TypeRefApi extends TypeApi { this: TypeRef => /** The prefix of the type reference. @@ -445,11 +491,14 @@ trait Types { self: Universe => } /** A subtype of Type representing refined types as well as `ClassInfo` signatures. + * @template + * @group Types */ type CompoundType >: Null <: AnyRef with Type /** A tag that preserves the identity of the `CompoundType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val CompoundTypeTag: ClassTag[CompoundType] @@ -460,20 +509,26 @@ trait Types { self: Universe => * P_1 with ... with P_m RefinedType(List(P_1, ..., P_m), Scope()) * { D_1; ...; D_n} RefinedType(List(AnyRef), Scope(D_1, ..., D_n)) * }}} + * @template + * @group Types */ type RefinedType >: Null <: AnyRef with CompoundType with RefinedTypeApi /** A tag that preserves the identity of the `RefinedType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val RefinedTypeTag: ClassTag[RefinedType] - /** The constructor/deconstructor for `RefinedType` instances. */ + /** The constructor/deconstructor for `RefinedType` instances. + * @group Extractors + */ val RefinedType: RefinedTypeExtractor /** An extractor class to create and pattern match with syntax `RefinedType(parents, decls)` * Here, `parents` is the list of parent types of the class, and `decls` is the scope * containing all declarations in the class. + * @group Extractors */ abstract class RefinedTypeExtractor { def apply(parents: List[Type], decls: Scope): RefinedType @@ -487,6 +542,7 @@ trait Types { self: Universe => /** The API that all refined types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait RefinedTypeApi extends TypeApi { this: RefinedType => /** The superclasses of the type. */ @@ -505,21 +561,27 @@ trait Types { self: Universe => * {{{ * ClassInfo(List(P_1, ..., P_m), Scope(D_1, ..., D_n), C) * }}} + * @template + * @group Types */ type ClassInfoType >: Null <: AnyRef with CompoundType with ClassInfoTypeApi /** A tag that preserves the identity of the `ClassInfoType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ClassInfoTypeTag: ClassTag[ClassInfoType] - /** The constructor/deconstructor for `ClassInfoType` instances. */ + /** The constructor/deconstructor for `ClassInfoType` instances. + * @group Extractors + */ val ClassInfoType: ClassInfoTypeExtractor /** An extractor class to create and pattern match with syntax `ClassInfo(parents, decls, clazz)` * Here, `parents` is the list of parent types of the class, `decls` is the scope * containing all declarations in the class, and `clazz` is the symbol of the class * itself. + * @group Extractors */ abstract class ClassInfoTypeExtractor { def apply(parents: List[Type], decls: Scope, typeSymbol: Symbol): ClassInfoType @@ -528,6 +590,7 @@ trait Types { self: Universe => /** The API that all class info types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait ClassInfoTypeApi extends TypeApi { this: ClassInfoType => /** The superclasses of the class type. */ @@ -541,15 +604,20 @@ trait Types { self: Universe => } /** The `MethodType` type signature is used to indicate parameters and result type of a method + * @template + * @group Types */ type MethodType >: Null <: AnyRef with Type with MethodTypeApi /** A tag that preserves the identity of the `MethodType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val MethodTypeTag: ClassTag[MethodType] - /** The constructor/deconstructor for `MethodType` instances. */ + /** The constructor/deconstructor for `MethodType` instances. + * @group Extractors + */ val MethodType: MethodTypeExtractor /** An extractor class to create and pattern match with syntax `MethodType(params, respte)` @@ -565,6 +633,7 @@ trait Types { self: Universe => * def f: Int * }}} * its type is a `NullaryMethodType`. + * @group Extractors */ abstract class MethodTypeExtractor { def apply(params: List[Symbol], resultType: Type): MethodType @@ -573,6 +642,7 @@ trait Types { self: Universe => /** The API that all method types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait MethodTypeApi extends TypeApi { this: MethodType => /** The symbols that correspond to the parameters of the method. */ @@ -584,19 +654,25 @@ trait Types { self: Universe => /** The `NullaryMethodType` type signature is used for parameterless methods * with declarations of the form `def foo: T` + * @template + * @group Types */ type NullaryMethodType >: Null <: AnyRef with Type with NullaryMethodTypeApi /** A tag that preserves the identity of the `NullaryMethodType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val NullaryMethodTypeTag: ClassTag[NullaryMethodType] - /** The constructor/deconstructor for `NullaryMethodType` instances. */ + /** The constructor/deconstructor for `NullaryMethodType` instances. + * @group Extractors + */ val NullaryMethodType: NullaryMethodTypeExtractor /** An extractor class to create and pattern match with syntax `NullaryMethodType(resultType)`. * Here, `resultType` is the result type of the parameterless method. + * @group Extractors */ abstract class NullaryMethodTypeExtractor { def apply(resultType: Type): NullaryMethodType @@ -605,6 +681,7 @@ trait Types { self: Universe => /** The API that all nullary method types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait NullaryMethodTypeApi extends TypeApi { this: NullaryMethodType => /** The result type of the method. */ @@ -613,20 +690,26 @@ trait Types { self: Universe => /** The `PolyType` type signature is used for polymorphic methods * that have at least one type parameter. + * @template + * @group Types */ type PolyType >: Null <: AnyRef with Type with PolyTypeApi /** A tag that preserves the identity of the `PolyType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val PolyTypeTag: ClassTag[PolyType] - /** The constructor/deconstructor for `PolyType` instances. */ + /** The constructor/deconstructor for `PolyType` instances. + * @group Extractors + */ val PolyType: PolyTypeExtractor /** An extractor class to create and pattern match with syntax `PolyType(typeParams, resultType)`. * Here, `typeParams` are the type parameters of the method and `resultType` * is the type signature following the type parameters. + * @group Extractors */ abstract class PolyTypeExtractor { def apply(typeParams: List[Symbol], resultType: Type): PolyType @@ -635,6 +718,7 @@ trait Types { self: Universe => /** The API that all polymorphic types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait PolyTypeApi extends TypeApi { this: PolyType => /** The symbols corresponding to the type parameters. */ @@ -646,21 +730,27 @@ trait Types { self: Universe => /** The `ExistentialType` type signature is used for existential types and * wildcard types. + * @template + * @group Types */ type ExistentialType >: Null <: AnyRef with Type with ExistentialTypeApi /** A tag that preserves the identity of the `ExistentialType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val ExistentialTypeTag: ClassTag[ExistentialType] - /** The constructor/deconstructor for `ExistentialType` instances. */ + /** The constructor/deconstructor for `ExistentialType` instances. + * @group Extractors + */ val ExistentialType: ExistentialTypeExtractor /** An extractor class to create and pattern match with syntax * `ExistentialType(quantified, underlying)`. * Here, `quantified` are the type variables bound by the existential type and `underlying` * is the type that's existentially quantified. + * @group Extractors */ abstract class ExistentialTypeExtractor { def apply(quantified: List[Symbol], underlying: Type): ExistentialType @@ -669,6 +759,7 @@ trait Types { self: Universe => /** The API that all existential types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait ExistentialTypeApi extends TypeApi { this: ExistentialType => /** The symbols corresponding to the `forSome` clauses of the existential type. */ @@ -680,21 +771,27 @@ trait Types { self: Universe => /** The `AnnotatedType` type signature is used for annotated types of the * for ` @`. + * @template + * @group Types */ type AnnotatedType >: Null <: AnyRef with Type with AnnotatedTypeApi /** A tag that preserves the identity of the `AnnotatedType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val AnnotatedTypeTag: ClassTag[AnnotatedType] - /** The constructor/deconstructor for `AnnotatedType` instances. */ + /** The constructor/deconstructor for `AnnotatedType` instances. + * @group Extractors + */ val AnnotatedType: AnnotatedTypeExtractor /** An extractor class to create and pattern match with syntax * `AnnotatedType(annotations, underlying, selfsym)`. * Here, `annotations` are the annotations decorating the underlying type `underlying`. * `selfSym` is a symbol representing the annotated type itself. + * @group Extractors */ abstract class AnnotatedTypeExtractor { def apply(annotations: List[Annotation], underlying: Type, selfsym: Symbol): AnnotatedType @@ -703,6 +800,7 @@ trait Types { self: Universe => /** The API that all annotated types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait AnnotatedTypeApi extends TypeApi { this: AnnotatedType => /** The annotations. */ @@ -724,20 +822,26 @@ trait Types { self: Universe => * T >: L TypeBounds(L, Any) * T <: U TypeBounds(Nothing, U) * }}} + * @template + * @group Types */ type TypeBounds >: Null <: AnyRef with Type with TypeBoundsApi /** A tag that preserves the identity of the `TypeBounds` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val TypeBoundsTag: ClassTag[TypeBounds] - /** The constructor/deconstructor for `TypeBounds` instances. */ + /** The constructor/deconstructor for `TypeBounds` instances. + * @group Extractors + */ val TypeBounds: TypeBoundsExtractor /** An extractor class to create and pattern match with syntax `TypeBound(lower, upper)` * Here, `lower` is the lower bound of the `TypeBounds` pair, and `upper` is * the upper bound. + * @group Extractors */ abstract class TypeBoundsExtractor { def apply(lo: Type, hi: Type): TypeBounds @@ -746,6 +850,7 @@ trait Types { self: Universe => /** The API that all type bounds support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait TypeBoundsApi extends TypeApi { this: TypeBounds => /** The lower bound. @@ -761,6 +866,7 @@ trait Types { self: Universe => /** An object representing an unknown type, used during type inference. * If you see WildcardType outside of inference it is almost certainly a bug. + * @group Types */ val WildcardType: Type @@ -773,19 +879,25 @@ trait Types { self: Universe => * the name of a method in the converted type, a HasMethodMatching * type is created: a MethodType with parameters typed as * BoundedWildcardTypes. + * @template + * @group Types */ type BoundedWildcardType >: Null <: AnyRef with Type with BoundedWildcardTypeApi /** A tag that preserves the identity of the `BoundedWildcardType` abstract type from erasure. * Can be used for pattern matching, instance tests, serialization and likes. + * @group Tags */ implicit val BoundedWildcardTypeTag: ClassTag[BoundedWildcardType] - /** The constructor/deconstructor for `BoundedWildcardType` instances. */ + /** The constructor/deconstructor for `BoundedWildcardType` instances. + * @group Extractors + */ val BoundedWildcardType: BoundedWildcardTypeExtractor /** An extractor class to create and pattern match with syntax `BoundedWildcardTypeExtractor(bounds)` * with `bounds` denoting the type bounds. + * @group Extractors */ abstract class BoundedWildcardTypeExtractor { def apply(bounds: TypeBounds): BoundedWildcardType @@ -794,37 +906,50 @@ trait Types { self: Universe => /** The API that all this types support. * The main source of information about types is the [[scala.reflect.api.Types]] page. + * @group API */ trait BoundedWildcardTypeApi extends TypeApi { this: BoundedWildcardType => /** Type bounds for the wildcard type. */ val bounds: TypeBounds } - /** The least upper bound of a list of types, as determined by `<:<`. */ + /** The least upper bound of a list of types, as determined by `<:<`. + * @group TypeOps + */ def lub(xs: List[Type]): Type - /** The greatest lower bound of a list of types, as determined by `<:<`. */ + /** The greatest lower bound of a list of types, as determined by `<:<`. + * @group TypeOps + */ def glb(ts: List[Type]): Type // Creators --------------------------------------------------------------- // too useful and too non-trivial to be left out of public API - /** The canonical creator for single-types */ + /** The canonical creator for single-types + * @group TypeCreators + */ def singleType(pre: Type, sym: Symbol): Type - /** the canonical creator for a refined type with a given scope */ + /** the canonical creator for a refined type with a given scope + * @group TypeCreators + */ def refinedType(parents: List[Type], owner: Symbol, decls: Scope, pos: Position): Type /** The canonical creator for a refined type with an initially empty scope. + * @group TypeCreators */ def refinedType(parents: List[Type], owner: Symbol): Type /** The canonical creator for typerefs + * @group TypeCreators */ def typeRef(pre: Type, sym: Symbol, args: List[Type]): Type /** A creator for intersection type where intersections of a single type are - * replaced by the type itself. */ + * replaced by the type itself. + * @group TypeCreators + */ def intersectionType(tps: List[Type]): Type /** A creator for intersection type where intersections of a single type are @@ -832,15 +957,19 @@ trait Types { self: Universe => * * !!! Repeated parent classes are not merged - is this a bug in the * comment or in the code? + * @group TypeCreators */ def intersectionType(tps: List[Type], owner: Symbol): Type - /** A creator for type applications */ + /** A creator for type applications + * @group Types + */ def appliedType(tycon: Type, args: List[Type]): Type /** A creator for type parameterizations that strips empty type parameter lists. * Use this factory method to indicate the type has kind * (it's a polymorphic value) * until we start tracking explicit kinds equivalent to typeFun (except that the latter requires tparams nonEmpty). + * @group Types */ def polyType(tparams: List[Symbol], tpe: Type): Type @@ -861,6 +990,7 @@ trait Types { self: Universe => * The abstraction drops all type parameters that are not directly or * indirectly referenced by type `tpe1`. If there are no remaining type * parameters, simply returns result type `tpe`. + * @group TypeCreators */ def existentialAbstraction(tparams: List[Symbol], tpe0: Type): Type } diff --git a/src/reflect/scala/reflect/api/Universe.scala b/src/reflect/scala/reflect/api/Universe.scala index 207dc98a91..c047d1641e 100644 --- a/src/reflect/scala/reflect/api/Universe.scala +++ b/src/reflect/scala/reflect/api/Universe.scala @@ -70,6 +70,7 @@ package api * by an abstract type `X`, optionally together with a class `XApi` that defines `X`'s' interface. * `X`'s companion object, if it exists, is represented by a value `X` that is of type `XExtractor`. * Moreover, for each type `X`, there is a value `XTag` of type `ClassTag[X]` that allows to pattern match on `X`. + * @groupprio Universe -1 */ abstract class Universe extends Symbols with Types @@ -96,8 +97,8 @@ abstract class Universe extends Symbols * * {{{ * val five = reify{ 5 } // Literal(Constant(5)) - * reify{ 2 + 4 } // Apply( Select( Literal(Constant(2)), newTermName("$plus")), List( Literal(Constant(4)) ) ) - * reify{ five.splice + 4 } // Apply( Select( Literal(Constant(5)), newTermName("$plus")), List( Literal(Constant(4)) ) ) + * reify{ 2 + 4 } // Apply( Select( Literal(Constant(2)), newTermName("\$plus")), List( Literal(Constant(4)) ) ) + * reify{ five.splice + 4 } // Apply( Select( Literal(Constant(5)), newTermName("\$plus")), List( Literal(Constant(4)) ) ) * }}} * * The produced tree is path dependent on the Universe `reify` was called from. @@ -128,7 +129,7 @@ abstract class Universe extends Symbols * * {{{ * val two = mirror.reify(2) // Literal(Constant(2)) - * val four = mirror.reify(two.splice + two.splice) // Apply(Select(two.tree, newTermName("$plus")), List(two.tree)) + * val four = mirror.reify(two.splice + two.splice) // Apply(Select(two.tree, newTermName("\$plus")), List(two.tree)) * * def macroImpl[T](c: Context) = { * ... @@ -145,6 +146,7 @@ abstract class Universe extends Symbols * locally defined entities get erased and replaced with their original trees * - Free variables are detected and wrapped in symbols of the type `FreeTermSymbol` or `FreeTypeSymbol` * - Mutable variables that are accessed from a local function are wrapped in refs + * @group Universe */ // implementation is hardwired to `scala.reflect.reify.Taggers` // using the mechanism implemented in `scala.tools.reflect.FastTrack` diff --git a/src/reflect/scala/reflect/macros/Context.scala b/src/reflect/scala/reflect/macros/Context.scala index 1c01bbd5dc..1f6e97adbc 100644 --- a/src/reflect/scala/reflect/macros/Context.scala +++ b/src/reflect/scala/reflect/macros/Context.scala @@ -73,7 +73,7 @@ trait Context extends Aliases * x: Coll[String] = ... * * scala> x.filter(_ != "") - * $line11.$read.$iw.$iw.$iw.$iw.$iw.$iw.$iw.$iw.$iw.$iw.$iw.$iw.x + * \$line11.\$read.\$iw.\$iw.\$iw.\$iw.\$iw.\$iw.\$iw.\$iw.\$iw.\$iw.\$iw.\$iw.x * res1 @ 35563b4b: x.type = ... * }}} * diff --git a/src/reflect/scala/reflect/macros/Evals.scala b/src/reflect/scala/reflect/macros/Evals.scala index 69885c219c..6aab3d5b02 100644 --- a/src/reflect/scala/reflect/macros/Evals.scala +++ b/src/reflect/scala/reflect/macros/Evals.scala @@ -19,7 +19,7 @@ trait Evals { * {{{ * scala> def impl(c: Context)(x: c.Expr[String]) = { * | val x1 = c.Expr[String](c.resetAllAttrs(x.tree.duplicate)) - * | println(s"compile-time value is: ${c.eval(x1)}") + * | println(s"compile-time value is: \${c.eval(x1)}") * | x * | } * impl: (c: Context)(x: c.Expr[String])c.Expr[String] diff --git a/src/reflect/scala/reflect/macros/Parsers.scala b/src/reflect/scala/reflect/macros/Parsers.scala index daf490c275..bf73c36b1b 100644 --- a/src/reflect/scala/reflect/macros/Parsers.scala +++ b/src/reflect/scala/reflect/macros/Parsers.scala @@ -14,6 +14,6 @@ trait Parsers { def parse(code: String): Tree } -/** Indicates an error during [[scala.reflect.macros.Parsers#Parse]]. +/** Indicates an error during [[scala.reflect.macros.Parsers#parse]]. */ case class ParseException(val pos: scala.reflect.api.Position, val msg: String) extends Exception(msg) diff --git a/src/reflect/scala/reflect/macros/Universe.scala b/src/reflect/scala/reflect/macros/Universe.scala index f270671fb1..7c308fe4bf 100644 --- a/src/reflect/scala/reflect/macros/Universe.scala +++ b/src/reflect/scala/reflect/macros/Universe.scala @@ -6,14 +6,19 @@ package macros * This universe provides mutability for reflection artifacts (e.g. macros can change types of compiler trees, * add annotation to symbols representing definitions, etc) and exposes some internal compiler functionality * such as `Symbol.deSkolemize` or `Tree.attachments`. + * @groupname Macros Macro Specific Additions + * @groupprio Macros -1 */ abstract class Universe extends scala.reflect.api.Universe { - /** A factory that encapsulates common tree-building functions. */ + /** A factory that encapsulates common tree-building functions. + * @group Macros + */ val treeBuild: TreeBuilder { val global: Universe.this.type } /** The API of reflection artifacts that support [[scala.reflect.macros.Attachments]]. * These artifacts are trees and symbols. + * @group Macros */ trait AttachableApi { /** The attachment of the reflection artifact. */ @@ -33,9 +38,14 @@ abstract class Universe extends scala.reflect.api.Universe { // Symbol extensions --------------------------------------------------------------- + /** The `Symbol` API is extended for macros: See [[SymbolContextApi]] for details. + * + * @group Macros + */ override type Symbol >: Null <: SymbolContextApi /** The extended API of symbols that's supported in macro context universes + * @group API */ trait SymbolContextApi extends SymbolApi with AttachableApi { self: Symbol => @@ -81,9 +91,14 @@ abstract class Universe extends scala.reflect.api.Universe { // Tree extensions --------------------------------------------------------------- + /** The `Tree` API is extended for macros: See [[TreeContextApi]] for details. + * + * @group Macros + */ override type Tree >: Null <: TreeContextApi /** The extended API of trees that's supported in macro context universes + * @group API */ trait TreeContextApi extends TreeApi with AttachableApi { self: Tree => @@ -102,7 +117,7 @@ abstract class Universe extends scala.reflect.api.Universe { /** Like `setType`, but if this is a previously empty TypeTree that * fact is remembered so that resetAllAttrs will snap back. * - * @PP: Attempting to elaborate on the above, I find: If defineType + * \@PP: Attempting to elaborate on the above, I find: If defineType * is called on a TypeTree whose type field is null or NoType, * this is recorded as "wasEmpty = true". That value is used in * ResetAttrsTraverser, which nulls out the type field of TypeTrees @@ -129,6 +144,7 @@ abstract class Universe extends scala.reflect.api.Universe { override type SymTree >: Null <: Tree with SymTreeContextApi /** The extended API of sym trees that's supported in macro context universes + * @group API */ trait SymTreeContextApi extends SymTreeApi { this: SymTree => /** Sets the `symbol` field of the sym tree. */ @@ -139,6 +155,7 @@ abstract class Universe extends scala.reflect.api.Universe { override type TypeTree >: Null <: TypTree with TypeTreeContextApi /** The extended API of sym trees that's supported in macro context universes + * @group API */ trait TypeTreeContextApi extends TypeTreeApi { this: TypeTree => /** Sets the `original` field of the type tree. */ @@ -149,6 +166,7 @@ abstract class Universe extends scala.reflect.api.Universe { override type Ident >: Null <: RefTree with IdentContextApi /** The extended API of idents that's supported in macro context universes + * @group API */ trait IdentContextApi extends IdentApi { this: Ident => /** Was this ident created from a backquoted identifier? */ @@ -156,24 +174,31 @@ abstract class Universe extends scala.reflect.api.Universe { } /** Mark a variable as captured; i.e. force boxing in a *Ref type. + * @group Macros */ def captureVariable(vble: Symbol): Unit /** Mark given identifier as a reference to a captured variable itself * suppressing dereferencing with the `elem` field. + * @group Macros */ def referenceCapturedVariable(vble: Symbol): Tree /** Convert type of a captured variable to *Ref type. + * @group Macros */ def capturedVariableType(vble: Symbol): Type - /** The type of compilation runs. */ + /** The type of compilation runs. + * @template + * @group Macros + */ type Run <: RunContextApi /** Compilation run uniquely identifies current invocation of the compiler * (e.g. can be used to implement per-run caches for macros) and provides access to units of work * of the invocation (currently processed unit of work and the list of all units). + * @group API */ trait RunContextApi { /** Currently processed unit of work (a real or a virtual file). */ @@ -183,11 +208,15 @@ abstract class Universe extends scala.reflect.api.Universe { def units: Iterator[CompilationUnit] } - /** The type of compilation units. */ + /** The type of compilation units. + * @template + * @group Macros + */ type CompilationUnit <: CompilationUnitContextApi /** Compilation unit describes a unit of work of the compilation run. * It provides such information as file name, textual representation of the unit and the underlying AST. + * @group API */ trait CompilationUnitContextApi { /** Source file corresponding to this compilation unit. diff --git a/src/reflect/scala/reflect/macros/package.scala b/src/reflect/scala/reflect/macros/package.scala index 84a307e60e..3a2f04bcf2 100644 --- a/src/reflect/scala/reflect/macros/package.scala +++ b/src/reflect/scala/reflect/macros/package.scala @@ -6,7 +6,7 @@ package scala.reflect * Within these functions the programmer has access to compiler APIs exposed in [[scala.reflect.macros.Context]]. * For example, it is possible to generate, analyze and typecheck code. * - * See the [[docs.scala-lang.org/overviews/macros.html Macros Guide]] on how to get started with Scala macros. + * See the [[http://docs.scala-lang.org/overviews/macros.html Macros Guide]] on how to get started with Scala macros. */ package object macros { } \ No newline at end of file -- cgit v1.2.3