From 06c71e7743259b0bc4670590dcdf3273d04d0953 Mon Sep 17 00:00:00 2001 From: Heather Miller Date: Fri, 2 Nov 2012 02:32:07 +0100 Subject: SI-6132 Revisited, cleaned-up, links fixed, spelling errors fixed, rewordings --- src/reflect/scala/reflect/api/Annotations.scala | 17 +-- src/reflect/scala/reflect/api/Constants.scala | 3 +- src/reflect/scala/reflect/api/Exprs.scala | 6 +- src/reflect/scala/reflect/api/FlagSets.scala | 10 +- src/reflect/scala/reflect/api/Importers.scala | 15 +-- src/reflect/scala/reflect/api/JavaMirrors.scala | 1 + src/reflect/scala/reflect/api/JavaUniverse.scala | 2 + src/reflect/scala/reflect/api/Mirror.scala | 3 +- src/reflect/scala/reflect/api/Mirrors.scala | 11 +- src/reflect/scala/reflect/api/Names.scala | 23 ++-- src/reflect/scala/reflect/api/Position.scala | 4 +- src/reflect/scala/reflect/api/Positions.scala | 1 + src/reflect/scala/reflect/api/Printers.scala | 13 ++- src/reflect/scala/reflect/api/Scopes.scala | 2 + .../scala/reflect/api/StandardDefinitions.scala | 2 + src/reflect/scala/reflect/api/StandardNames.scala | 1 + src/reflect/scala/reflect/api/Symbols.scala | 35 +++++- src/reflect/scala/reflect/api/TagInterop.scala | 2 + src/reflect/scala/reflect/api/TreeCreator.scala | 2 + src/reflect/scala/reflect/api/Trees.scala | 120 ++++++++++++--------- src/reflect/scala/reflect/api/TypeCreator.scala | 2 + src/reflect/scala/reflect/api/TypeTags.scala | 19 +--- src/reflect/scala/reflect/api/Types.scala | 106 ++++++++---------- src/reflect/scala/reflect/api/Universe.scala | 11 +- src/reflect/scala/reflect/api/package.scala | 3 +- src/reflect/scala/reflect/macros/TreeBuilder.scala | 7 -- 26 files changed, 227 insertions(+), 194 deletions(-) diff --git a/src/reflect/scala/reflect/api/Annotations.scala b/src/reflect/scala/reflect/api/Annotations.scala index ebfd57038c..09eaf7afb4 100644 --- a/src/reflect/scala/reflect/api/Annotations.scala +++ b/src/reflect/scala/reflect/api/Annotations.scala @@ -16,9 +16,9 @@ import scala.collection.immutable.ListMap * is automatically added as a subclass to every Java annotation. *
  • ''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 + * + * 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 @@ -32,7 +32,10 @@ import scala.collection.immutable.ListMap * - arrays and * - nested annotations. * + * For more information about `Annotation`s, see the [[http://docs.scala-lang.org/overviews/reflection/annotations-names-scopes.html Reflection Guide: Annotations, Names, Scopes, and More]] + * * @contentDiagram hideNodes "*Api" + * @group ReflectionAPI */ trait Annotations { self: Universe => @@ -48,7 +51,7 @@ trait Annotations { self: Universe => */ implicit val AnnotationTag: ClassTag[Annotation] - /** The constructor/deconstructor for `Annotation` instances. + /** The constructor/extractor for `Annotation` instances. * @group Extractors */ val Annotation: AnnotationExtractor @@ -105,7 +108,7 @@ trait Annotations { self: Universe => */ implicit val LiteralArgumentTag: ClassTag[LiteralArgument] - /** The constructor/deconstructor for `LiteralArgument` instances. + /** The constructor/extractor for `LiteralArgument` instances. * @group Extractors */ val LiteralArgument: LiteralArgumentExtractor @@ -140,7 +143,7 @@ trait Annotations { self: Universe => */ implicit val ArrayArgumentTag: ClassTag[ArrayArgument] - /** The constructor/deconstructor for `ArrayArgument` instances. + /** The constructor/extractor for `ArrayArgument` instances. * @group Extractors */ val ArrayArgument: ArrayArgumentExtractor @@ -175,7 +178,7 @@ trait Annotations { self: Universe => */ implicit val NestedArgumentTag: ClassTag[NestedArgument] - /** The constructor/deconstructor for `NestedArgument` instances. + /** The constructor/extractor for `NestedArgument` instances. * @group Extractors */ val NestedArgument: NestedArgumentExtractor diff --git a/src/reflect/scala/reflect/api/Constants.scala b/src/reflect/scala/reflect/api/Constants.scala index 89153706ed..4a8a2868cc 100644 --- a/src/reflect/scala/reflect/api/Constants.scala +++ b/src/reflect/scala/reflect/api/Constants.scala @@ -84,6 +84,7 @@ package api * }}} * * @contentDiagram hideNodes "*Api" + * @group ReflectionAPI */ trait Constants { self: Universe => @@ -188,7 +189,7 @@ trait Constants { */ implicit val ConstantTag: ClassTag[Constant] - /** The constructor/deconstructor for `Constant` instances. + /** The constructor/extractor for `Constant` instances. * @group Extractors */ val Constant: ConstantExtractor diff --git a/src/reflect/scala/reflect/api/Exprs.scala b/src/reflect/scala/reflect/api/Exprs.scala index 739b9dca12..eeef94598c 100644 --- a/src/reflect/scala/reflect/api/Exprs.scala +++ b/src/reflect/scala/reflect/api/Exprs.scala @@ -27,6 +27,8 @@ import scala.reflect.runtime.{universe => ru} * 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#universe]], the default mirror is typically [[scala.reflect.runtime#currentMirror]]. + * + * @group ReflectionAPI */ trait Exprs { self: Universe => @@ -106,16 +108,12 @@ trait Exprs { self: Universe => */ val value: T - /** TODO how do I doc this? */ override def canEqual(x: Any) = x.isInstanceOf[Expr[_]] - /** TODO how do I doc this? */ override def equals(x: Any) = x.isInstanceOf[Expr[_]] && this.mirror == x.asInstanceOf[Expr[_]].mirror && this.tree == x.asInstanceOf[Expr[_]].tree - /** TODO how do I doc this? */ override def hashCode = mirror.hashCode * 31 + tree.hashCode - /** TODO how do I doc this? */ override def toString = "Expr["+staticType+"]("+tree+")" } diff --git a/src/reflect/scala/reflect/api/FlagSets.scala b/src/reflect/scala/reflect/api/FlagSets.scala index 5cf7460dcd..4357aec9c9 100644 --- a/src/reflect/scala/reflect/api/FlagSets.scala +++ b/src/reflect/scala/reflect/api/FlagSets.scala @@ -21,8 +21,8 @@ import scala.language.implicitConversions * {{{ * ClassDef(Modifiers(NoFlags), newTypeName("C"), Nil, ...) * }}} - * - * Here, the flag set is empty. + * + * Here, the flag set is empty. * * To make `C` private, one would write something like: * {{{ @@ -36,7 +36,7 @@ import scala.language.implicitConversions * }}} * * The list of all available flags is defined in [[scala.reflect.api.FlagSets#FlagValues]], available via - * [[scala.reflect.api.FlagSets#Flag]]. (Typically one writes a blanket import for this, e.g. + * [[scala.reflect.api.FlagSets#Flag]]. (Typically one writes a wildcard import for this, e.g. * `import scala.reflect.runtime.universe.Flag._`). * * Definition trees are compiled down to symbols, so flags on modifiers of these trees are transformed into flags @@ -47,9 +47,11 @@ import scala.language.implicitConversions * ''Of Note:'' This part of the Reflection API is being considered as a candidate for redesign. It is * quite possible that in future releases of the reflection API, flag sets could be replaced with something else. * - * For more details about `FlagSet`s and other aspects of Scala reflection, see the + * For more details about `FlagSet`s and other aspects of Scala reflection, see the * [[http://docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] * + * @group ReflectionAPI + * */ trait FlagSets { self: Universe => diff --git a/src/reflect/scala/reflect/api/Importers.scala b/src/reflect/scala/reflect/api/Importers.scala index f68ff690cf..afc4f2f25d 100644 --- a/src/reflect/scala/reflect/api/Importers.scala +++ b/src/reflect/scala/reflect/api/Importers.scala @@ -5,16 +5,17 @@ package api * EXPERIMENTAL * * This trait provides support for importers, a facility to migrate reflection artifacts between universes. + * ''Note: this trait should typically be used only rarely.'' * * Reflection artifacts, such as [[scala.reflect.api.Symbols Symbols]] and [[scala.reflect.api.Types Types]], - * are contained in [[scala.reflect.api.Universes Universe]]s. 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 + * are contained in [[scala.reflect.api.Universes Universe]]s. 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 `Universe`s, which is reflected by the fact that types of artifacts - * from different universes are not compatible. By using `Importer`s, however, they be imported from one universe + * Reflection artifacts are firmly grounded in their `Universe`s, which is reflected by the fact that types of artifacts + * from different universes are not compatible. By using `Importer`s, 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 @@ -55,6 +56,8 @@ package api * ... * } * }}} + * + * @group ReflectionAPI */ trait Importers { self: Universe => diff --git a/src/reflect/scala/reflect/api/JavaMirrors.scala b/src/reflect/scala/reflect/api/JavaMirrors.scala index 43360c97a1..b678033e1a 100644 --- a/src/reflect/scala/reflect/api/JavaMirrors.scala +++ b/src/reflect/scala/reflect/api/JavaMirrors.scala @@ -15,6 +15,7 @@ package api * [[http://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html Reflection Guide: Mirrors]] * * @groupname JavaMirrors Java Mirrors + * @group ReflectionAPI */ trait JavaMirrors { self: JavaUniverse => diff --git a/src/reflect/scala/reflect/api/JavaUniverse.scala b/src/reflect/scala/reflect/api/JavaUniverse.scala index 8649f339e3..04d091ee9d 100644 --- a/src/reflect/scala/reflect/api/JavaUniverse.scala +++ b/src/reflect/scala/reflect/api/JavaUniverse.scala @@ -10,7 +10,9 @@ package api * to [[scala.reflect.api.JavaMirrors#JavaMirror]]. * * 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 + * @group ReflectionAPI * * @contentDiagram hideNodes "*Api" */ diff --git a/src/reflect/scala/reflect/api/Mirror.scala b/src/reflect/scala/reflect/api/Mirror.scala index f600ee9caf..1223326d7c 100644 --- a/src/reflect/scala/reflect/api/Mirror.scala +++ b/src/reflect/scala/reflect/api/Mirror.scala @@ -10,10 +10,11 @@ package api * for a complete overview of `Mirror`s. * * @tparam U the type of the universe this mirror belongs to. + * @group ReflectionAPI */ // 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. abstract class Mirror[U <: Universe with Singleton] { /** The universe this mirror belongs to. diff --git a/src/reflect/scala/reflect/api/Mirrors.scala b/src/reflect/scala/reflect/api/Mirrors.scala index c4573eaf99..d0d8a37584 100644 --- a/src/reflect/scala/reflect/api/Mirrors.scala +++ b/src/reflect/scala/reflect/api/Mirrors.scala @@ -17,13 +17,13 @@ package api * The two flavors of mirrors: * * - * + * * === Compile-time Mirrors === * Compile-time `Mirror`s make use of only classloader `Mirror`s to load `Symbol`s * by name. @@ -53,7 +53,7 @@ package api * lookup symbols. For example, `typeOf[Location.type].termSymbol` (or `typeOf[Location].typeSymbol` * if we needed a `ClassSymbol`), which are type safe since we don’t have to use `String`s to lookup * the `Symbol`. - * + * * === Runtime Mirrors === * * Runtime `Mirror`s make use of both classloader and invoker `Mirror`s. @@ -62,7 +62,7 @@ package api * `ru` is [[scala.reflect.runtime.universe]]. * * The result of a [[scala.reflect.api.JavaMirrors#runtimeMirror]] call is a classloader mirror, - * of type [[scala.reflect.api.Mirrors#ReflectiveMirror]], which can load symbols by names as + * of type [[scala.reflect.api.Mirrors#ReflectiveMirror]], which can load symbols by names as * discussed above (in the “Compile-time” section). * * A classloader mirror can create invoker mirrors, which include: [[scala.reflect.api.Mirrors#InstanceMirror]], @@ -205,6 +205,7 @@ package api * [[http://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html Reflection Guide: Mirrors]] * * @contentDiagram hideNodes "*Api" + * @group ReflectionAPI */ trait Mirrors { self: Universe => diff --git a/src/reflect/scala/reflect/api/Names.scala b/src/reflect/scala/reflect/api/Names.scala index 3d124dafc4..7c12f180a8 100644 --- a/src/reflect/scala/reflect/api/Names.scala +++ b/src/reflect/scala/reflect/api/Names.scala @@ -4,21 +4,26 @@ package api /** * EXPERIMENTAL * - * This trait defines Names (a Scala reflection concept) and operations on them. + * This trait defines `Name`s in Scala Reflection, 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. + * 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. * - * === Examples === + * To search for the `map` method (which is a term) declared in the `List` class, one can do: * - * To search for the `map` method (which is a term) declared in the `List` class, - * use `typeOf[List[_]].member(newTermName("map"))`. To search for a type member, use - * newTypeName instead. + * {{{ + * scala> typeOf[List[_]].member(newTermName("map")) + * res0: reflect.runtime.universe.Symbol = method map + * }}} * - * See the [[docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for more about Scala Reflection. + * To search for a type member, one can follow the same procedure, using `newTypeName` instead. + * + * For more information about creating and using `Name`s, see the [[http://docs.scala-lang.org/overviews/reflection/annotations-names-scopes.html Reflection Guide: Annotations, Names, Scopes, and More]] * * @contentDiagram hideNodes "*Api" + * @group ReflectionAPI */ trait Names { /** An implicit conversion from String to TermName. diff --git a/src/reflect/scala/reflect/api/Position.scala b/src/reflect/scala/reflect/api/Position.scala index 0dfd74f1b3..63c67627a3 100644 --- a/src/reflect/scala/reflect/api/Position.scala +++ b/src/reflect/scala/reflect/api/Position.scala @@ -9,14 +9,12 @@ import scala.reflect.macros.Attachments * Position tracks the origin of [[Symbols#Symbol symbols]] and [[Trees#Tree tree nodes]]. They are commonly used when * displaying warnings and errors, to indicate the incorrect point in the program. * - * A position indicates the [[source source file]] and a [[point offset]]. A position may be - * undefined, which means it's pointing to the [[Positions#NoPosition]] element. - * * Please note that this trait may be refactored in future versions of the Scala reflection API. * * For more information about `Position`s, see the [[http://docs.scala-lang.org/overviews/reflection/annotations-names-scopes.html Reflection Guide: Annotations, Names, Scopes, and More]] * * @groupname Common Commonly used methods + * @group ReflectionAPI */ trait Position extends Attachments { diff --git a/src/reflect/scala/reflect/api/Positions.scala b/src/reflect/scala/reflect/api/Positions.scala index 14cc0ab12c..87f00fdb88 100644 --- a/src/reflect/scala/reflect/api/Positions.scala +++ b/src/reflect/scala/reflect/api/Positions.scala @@ -9,6 +9,7 @@ package api * @see [[scala.reflect.api.Position]] * * @contentDiagram hideNodes "*Api" + * @group ReflectionAPI */ trait Positions { self: Universe => diff --git a/src/reflect/scala/reflect/api/Printers.scala b/src/reflect/scala/reflect/api/Printers.scala index b1e14f798f..85ddcc6523 100644 --- a/src/reflect/scala/reflect/api/Printers.scala +++ b/src/reflect/scala/reflect/api/Printers.scala @@ -33,7 +33,7 @@ import java.io.{ PrintWriter, StringWriter } * () * } * }}} - * + * * The method `showRaw` displays internal structure of a given reflection object * as a Scala abstract syntax tree (AST), the representation that the Scala typechecker * operates on. @@ -57,7 +57,7 @@ import java.io.{ PrintWriter, StringWriter } * Literal(Constant(2))))))), * Literal(Constant(()))) * }}} - * + * * The method `showRaw` can also print [[scala.reflect.api.Types]] next to the artifacts * being inspected * {{{ @@ -92,7 +92,7 @@ import java.io.{ PrintWriter, StringWriter } * * === Printing Types === * - * The method `show` + * The method `show` * {{{ * scala> import scala.reflect.runtime.universe._ * import scala.reflect.runtime.universe._ @@ -119,17 +119,20 @@ import java.io.{ PrintWriter, StringWriter } * * `printIds` and/or `printKinds` can additionally be supplied as arguments in a call to * `showRaw` which additionally shows the unique identifiers of symbols. + * + * {{{ * scala> showRaw(tpe, printIds = true, printKinds = true) * res2: String = RefinedType( * List(TypeRef(ThisType(scala#2043#PK), newTypeName("AnyRef")#691#TPE, List())), * Scope( * newTermName("x")#2540#METH, * newTermName("y")#2541#GET)) - * }}} + * }}} * - * For more details about `Printer`s and other aspects of Scala reflection, see the + * For more details about `Printer`s and other aspects of Scala reflection, see the * [[http://docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] * + * @group ReflectionAPI */ trait Printers { self: Universe => diff --git a/src/reflect/scala/reflect/api/Scopes.scala b/src/reflect/scala/reflect/api/Scopes.scala index c79ec06b45..7f9799393c 100644 --- a/src/reflect/scala/reflect/api/Scopes.scala +++ b/src/reflect/scala/reflect/api/Scopes.scala @@ -17,6 +17,8 @@ package api * Additional functionality is exposed in member scopes that are returned by * `members` and `declarations` defined in [[scala.reflect.api.Types#TypeApi]]. * Such scopes support the `sorted` method, which sorts members in declaration order. + * + * @group ReflectionAPI */ trait Scopes { self: Universe => diff --git a/src/reflect/scala/reflect/api/StandardDefinitions.scala b/src/reflect/scala/reflect/api/StandardDefinitions.scala index 480a28b878..61097e3f69 100644 --- a/src/reflect/scala/reflect/api/StandardDefinitions.scala +++ b/src/reflect/scala/reflect/api/StandardDefinitions.scala @@ -13,6 +13,8 @@ package api * These standard definitions can accessed to using `definitions`. * They're typically imported with a wildcard import, `import definitions._`, and are * listed in [[scala.reflect.api.StandardDefinitions#DefinitionsApi]]. + * + * @group ReflectionAPI */ trait StandardDefinitions { self: Universe => diff --git a/src/reflect/scala/reflect/api/StandardNames.scala b/src/reflect/scala/reflect/api/StandardNames.scala index 0c1ceae187..e24bc91ced 100644 --- a/src/reflect/scala/reflect/api/StandardNames.scala +++ b/src/reflect/scala/reflect/api/StandardNames.scala @@ -22,6 +22,7 @@ package api * * The API for names in Scala reflection. * @groupname StandardNames Standard Names + * @group ReflectionAPI */ trait StandardNames { self: Universe => diff --git a/src/reflect/scala/reflect/api/Symbols.scala b/src/reflect/scala/reflect/api/Symbols.scala index d91481724f..b53c700701 100644 --- a/src/reflect/scala/reflect/api/Symbols.scala +++ b/src/reflect/scala/reflect/api/Symbols.scala @@ -9,20 +9,49 @@ package api * Symbols are used to establish bindings between a name and the entity it refers to, such as a class or a method. * Anything you define and can give a name to in Scala has an associated symbol. * + * Symbols contain all available information about the declaration of an entity (class/object/trait etc.) or a + * member (vals/vars/defs etc.), and as such are an integral abstraction central to both runtime + * reflection and macros. + * + * A symbol can provide a wealth of information ranging from the basic `name` method available on all symbols to + * other, more involved, concepts such as getting the `baseClasses` from `ClassSymbol`. Other common use cases of + * symbols include inspecting members' signatures, getting type parameters of a class, getting the parameter type + * of a method or finding out the type of a field. + * + * Example usage of runtime reflection; getting a method's type signature: + * {{{ + * scala> import scala.reflect.runtime.universe._ + * import scala.reflect.runtime.universe._ + * + * scala> class C[T] { def test[U](x: T)(y: U): Int = ??? } + * defined class C + * + * scala> val test = typeOf[C[Int]].member(newTermName("test")).asMethod + * test: reflect.runtime.universe.MethodSymbol = method test + * + * scala> test.typeSignature + * res0: reflect.runtime.universe.Type = [U](x: T)(y: U)scala.Int + * }}} + * + * Symbols are organized in a hierarchy. For example, a symbol that represents a parameter of a method is owned by + * the corresponding method symbol, a method symbol is owned by its enclosing class, a class is owned by a + * containing package and so on. + * * Certain types of tree nodes, such as [[Trees#Ident Ident]] (references to identifiers) and * [[Trees#Select Select]] (references to members) expose method [[Trees.SymTreeApi.symbol `symbol`]] * to obtain the symbol that represents their declaration. During the typechecking phase, the compiler looks up the * symbol based on the name and scope and sets the [[Trees.SymTreeApi.symbol `symbol` field]] of tree nodes. * - * @contentDiagram hideNodes "*Api" + * For more information about `Symbol` usage and attached intricacies, see the [[http://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html Reflection Guide: Symbols]] * - * @see [[http://docs.scala-lang.org/overviews/reflection/overview.html]] + * @group ReflectionAPI * - * The Reflection Guide provides more details on symbol usage and attached intricacies. + * @contentDiagram hideNodes "*Api" * * @define SYMACCESSORS Class [[Symbol]] defines `isXXX` test methods such as `isPublic` or `isFinal`, `params` and * `returnType` methods for method symbols, `baseClasses` for class symbols and so on. Some of these methods don't * make sense for certain subclasses of `Symbol` and return `NoSymbol`, `Nil` or other empty values. + * */ trait Symbols { self: Universe => diff --git a/src/reflect/scala/reflect/api/TagInterop.scala b/src/reflect/scala/reflect/api/TagInterop.scala index 5486c34517..5de811578e 100644 --- a/src/reflect/scala/reflect/api/TagInterop.scala +++ b/src/reflect/scala/reflect/api/TagInterop.scala @@ -5,6 +5,8 @@ package api * EXPERIMENTAL * * This trait provides type tag <-> manifest interoperability. + * @group ReflectionAPI + * * @groupname TagInterop TypeTag and Manifest Interoperability */ trait TagInterop { self: Universe => diff --git a/src/reflect/scala/reflect/api/TreeCreator.scala b/src/reflect/scala/reflect/api/TreeCreator.scala index cba90b72e6..6969418470 100644 --- a/src/reflect/scala/reflect/api/TreeCreator.scala +++ b/src/reflect/scala/reflect/api/TreeCreator.scala @@ -4,6 +4,8 @@ package api /** This is an internal implementation class. * * This class is used internally by Scala Reflection, and is not recommended for use in client code. + * + * @group ReflectionAPI */ abstract class TreeCreator { def apply[U <: Universe with Singleton](m: scala.reflect.api.Mirror[U]): U # Tree diff --git a/src/reflect/scala/reflect/api/Trees.scala b/src/reflect/scala/reflect/api/Trees.scala index 87a0348c15..d34fb78b89 100644 --- a/src/reflect/scala/reflect/api/Trees.scala +++ b/src/reflect/scala/reflect/api/Trees.scala @@ -10,26 +10,39 @@ 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.Trees#Tree Tree]]. + * Trees are the basis for Scala's abstract syntax that is used to represent programs. They are also called + * abstract syntax trees and commonly abbreviated as ASTs. + * + * In Scala reflection, APIs that produce or use `Tree`s are: + * + * - '''Annotations''' which use trees to represent their arguments, exposed in [[scala.reflect.api.Annotations#scalaArgs Annotation.scalaArgs]]. + * - '''[[scala.reflect.api.Universe#reify reify]]''', a special method on [[scala.reflect.api.Universe]] that takes an expression and returns an AST which represents the expression. + * - '''Macros and runtime compilation with toolboxes''' which both use trees as their program representation medium. * * 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. + * === Examples === * - * [[scala.reflect.api.Universe#showRaw showRaw]] can be used to get a readable representation of a tree. + * The following creates an AST representing a literal 5 in Scala source code: + * {{{ + * Literal(Constant(5)) + * }}} * - * === Examples === - * `Literal(Constant(5))` creates an AST representing a literal 5 in Scala source code. + * The following creates an AST representing `print("Hello World")`: + * {{{ + * Apply(Select(Select(This(newTypeName("scala")), newTermName("Predef")), newTermName("print")), List(Literal(Constant("Hello World")))) + * }}} * - * `Apply(Select(Select(This(newTypeName("scala")), newTermName("Predef")), newTermName("print")), List(Literal(Constant("Hello World"))))` - * creates an AST representing `print("Hello World")`. + * The following creates an AST from a literal 5, and then uses `showRaw` to print it in a readable format. + * {{{ + * import scala.reflect.runtime.universe.{ reify, showRaw } + * print( showRaw( reify{5}.tree ) )` // prints Literal(Constant(5)) + * }}} * - * `import scala.reflect.runtime.universe.{reify,showRaw}` - * `print( showRaw( reify{5}.tree ) )` // prints Literal(Constant(5)) + * For more information about `Tree`s, see the [[http://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html Reflection Guide: Symbols, Trees, Types]]. * - * @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 @@ -37,6 +50,7 @@ package api * @groupprio Copying 1 * * @contentDiagram hideNodes "*Api" + * @group ReflectionAPI */ trait Trees { self: Universe => @@ -349,7 +363,7 @@ trait Trees { self: Universe => */ implicit val PackageDefTag: ClassTag[PackageDef] - /** The constructor/deconstructor for `PackageDef` instances. + /** The constructor/extractor for `PackageDef` instances. * @group Extractors */ val PackageDef: PackageDefExtractor @@ -408,7 +422,7 @@ trait Trees { self: Universe => */ implicit val ClassDefTag: ClassTag[ClassDef] - /** The constructor/deconstructor for `ClassDef` instances. + /** The constructor/extractor for `ClassDef` instances. * @group Extractors */ val ClassDef: ClassDefExtractor @@ -459,7 +473,7 @@ trait Trees { self: Universe => */ implicit val ModuleDefTag: ClassTag[ModuleDef] - /** The constructor/deconstructor for `ModuleDef` instances. + /** The constructor/extractor for `ModuleDef` instances. * @group Extractors */ val ModuleDef: ModuleDefExtractor @@ -542,7 +556,7 @@ trait Trees { self: Universe => */ implicit val ValDefTag: ClassTag[ValDef] - /** The constructor/deconstructor for `ValDef` instances. + /** The constructor/extractor for `ValDef` instances. * @group Extractors */ val ValDef: ValDefExtractor @@ -597,7 +611,7 @@ trait Trees { self: Universe => */ implicit val DefDefTag: ClassTag[DefDef] - /** The constructor/deconstructor for `DefDef` instances. + /** The constructor/extractor for `DefDef` instances. * @group Extractors */ val DefDef: DefDefExtractor @@ -652,7 +666,7 @@ trait Trees { self: Universe => */ implicit val TypeDefTag: ClassTag[TypeDef] - /** The constructor/deconstructor for `TypeDef` instances. + /** The constructor/extractor for `TypeDef` instances. * @group Extractors */ val TypeDef: TypeDefExtractor @@ -717,7 +731,7 @@ trait Trees { self: Universe => */ implicit val LabelDefTag: ClassTag[LabelDef] - /** The constructor/deconstructor for `LabelDef` instances. + /** The constructor/extractor for `LabelDef` instances. * @group Extractors */ val LabelDef: LabelDefExtractor @@ -779,7 +793,7 @@ trait Trees { self: Universe => */ implicit val ImportSelectorTag: ClassTag[ImportSelector] - /** The constructor/deconstructor for `ImportSelector` instances. + /** The constructor/extractor for `ImportSelector` instances. * @group Extractors */ val ImportSelector: ImportSelectorExtractor @@ -831,7 +845,7 @@ trait Trees { self: Universe => */ implicit val ImportTag: ClassTag[Import] - /** The constructor/deconstructor for `Import` instances. + /** The constructor/extractor for `Import` instances. * @group Extractors */ val Import: ImportExtractor @@ -889,7 +903,7 @@ trait Trees { self: Universe => */ implicit val TemplateTag: ClassTag[Template] - /** The constructor/deconstructor for `Template` instances. + /** The constructor/extractor for `Template` instances. * @group Extractors */ val Template: TemplateExtractor @@ -947,7 +961,7 @@ trait Trees { self: Universe => */ implicit val BlockTag: ClassTag[Block] - /** The constructor/deconstructor for `Block` instances. + /** The constructor/extractor for `Block` instances. * @group Extractors */ val Block: BlockExtractor @@ -992,7 +1006,7 @@ trait Trees { self: Universe => */ implicit val CaseDefTag: ClassTag[CaseDef] - /** The constructor/deconstructor for `CaseDef` instances. + /** The constructor/extractor for `CaseDef` instances. * @group Extractors */ val CaseDef: CaseDefExtractor @@ -1045,7 +1059,7 @@ trait Trees { self: Universe => */ implicit val AlternativeTag: ClassTag[Alternative] - /** The constructor/deconstructor for `Alternative` instances. + /** The constructor/extractor for `Alternative` instances. * @group Extractors */ val Alternative: AlternativeExtractor @@ -1083,7 +1097,7 @@ trait Trees { self: Universe => */ implicit val StarTag: ClassTag[Star] - /** The constructor/deconstructor for `Star` instances. + /** The constructor/extractor for `Star` instances. * @group Extractors */ val Star: StarExtractor @@ -1124,7 +1138,7 @@ trait Trees { self: Universe => */ implicit val BindTag: ClassTag[Bind] - /** The constructor/deconstructor for `Bind` instances. + /** The constructor/extractor for `Bind` instances. * @group Extractors */ val Bind: BindExtractor @@ -1193,7 +1207,7 @@ trait Trees { self: Universe => */ implicit val UnApplyTag: ClassTag[UnApply] - /** The constructor/deconstructor for `UnApply` instances. + /** The constructor/extractor for `UnApply` instances. * @group Extractors */ val UnApply: UnApplyExtractor @@ -1235,7 +1249,7 @@ trait Trees { self: Universe => */ implicit val FunctionTag: ClassTag[Function] - /** The constructor/deconstructor for `Function` instances. + /** The constructor/extractor for `Function` instances. * @group Extractors */ val Function: FunctionExtractor @@ -1279,7 +1293,7 @@ trait Trees { self: Universe => */ implicit val AssignTag: ClassTag[Assign] - /** The constructor/deconstructor for `Assign` instances. + /** The constructor/extractor for `Assign` instances. * @group Extractors */ val Assign: AssignExtractor @@ -1321,7 +1335,7 @@ trait Trees { self: Universe => */ implicit val AssignOrNamedArgTag: ClassTag[AssignOrNamedArg] - /** The constructor/deconstructor for `AssignOrNamedArg` instances. + /** The constructor/extractor for `AssignOrNamedArg` instances. * @group Extractors */ val AssignOrNamedArg: AssignOrNamedArgExtractor @@ -1368,7 +1382,7 @@ trait Trees { self: Universe => */ implicit val IfTag: ClassTag[If] - /** The constructor/deconstructor for `If` instances. + /** The constructor/extractor for `If` instances. * @group Extractors */ val If: IfExtractor @@ -1425,7 +1439,7 @@ trait Trees { self: Universe => */ implicit val MatchTag: ClassTag[Match] - /** The constructor/deconstructor for `Match` instances. + /** The constructor/extractor for `Match` instances. * @group Extractors */ val Match: MatchExtractor @@ -1466,7 +1480,7 @@ trait Trees { self: Universe => */ implicit val ReturnTag: ClassTag[Return] - /** The constructor/deconstructor for `Return` instances. + /** The constructor/extractor for `Return` instances. * @group Extractors */ val Return: ReturnExtractor @@ -1504,7 +1518,7 @@ trait Trees { self: Universe => */ implicit val TryTag: ClassTag[Try] - /** The constructor/deconstructor for `Try` instances. + /** The constructor/extractor for `Try` instances. * @group Extractors */ val Try: TryExtractor @@ -1548,7 +1562,7 @@ trait Trees { self: Universe => */ implicit val ThrowTag: ClassTag[Throw] - /** The constructor/deconstructor for `Throw` instances. + /** The constructor/extractor for `Throw` instances. * @group Extractors */ val Throw: ThrowExtractor @@ -1584,7 +1598,7 @@ trait Trees { self: Universe => */ implicit val NewTag: ClassTag[New] - /** The constructor/deconstructor for `New` instances. + /** The constructor/extractor for `New` instances. * @group Extractors */ val New: NewExtractor @@ -1631,7 +1645,7 @@ trait Trees { self: Universe => */ implicit val TypedTag: ClassTag[Typed] - /** The constructor/deconstructor for `Typed` instances. + /** The constructor/extractor for `Typed` instances. * @group Extractors */ val Typed: TypedExtractor @@ -1697,7 +1711,7 @@ trait Trees { self: Universe => */ implicit val TypeApplyTag: ClassTag[TypeApply] - /** The constructor/deconstructor for `TypeApply` instances. + /** The constructor/extractor for `TypeApply` instances. * @group Extractors */ val TypeApply: TypeApplyExtractor @@ -1731,7 +1745,7 @@ trait Trees { self: Universe => */ implicit val ApplyTag: ClassTag[Apply] - /** The constructor/deconstructor for `Apply` instances. + /** The constructor/extractor for `Apply` instances. * @group Extractors */ val Apply: ApplyExtractor @@ -1774,7 +1788,7 @@ trait Trees { self: Universe => */ implicit val SuperTag: ClassTag[Super] - /** The constructor/deconstructor for `Super` instances. + /** The constructor/extractor for `Super` instances. * @group Extractors */ val Super: SuperExtractor @@ -1826,7 +1840,7 @@ trait Trees { self: Universe => */ implicit val ThisTag: ClassTag[This] - /** The constructor/deconstructor for `This` instances. + /** The constructor/extractor for `This` instances. * @group Extractors */ val This: ThisExtractor @@ -1867,7 +1881,7 @@ trait Trees { self: Universe => */ implicit val SelectTag: ClassTag[Select] - /** The constructor/deconstructor for `Select` instances. + /** The constructor/extractor for `Select` instances. * @group Extractors */ val Select: SelectExtractor @@ -1906,7 +1920,7 @@ trait Trees { self: Universe => */ implicit val IdentTag: ClassTag[Ident] - /** The constructor/deconstructor for `Ident` instances. + /** The constructor/extractor for `Ident` instances. * @group Extractors */ val Ident: IdentExtractor @@ -1951,7 +1965,7 @@ trait Trees { self: Universe => */ implicit val ReferenceToBoxedTag: ClassTag[ReferenceToBoxed] - /** The constructor/deconstructor for `ReferenceToBoxed` instances. + /** The constructor/extractor for `ReferenceToBoxed` instances. * @group Extractors */ val ReferenceToBoxed: ReferenceToBoxedExtractor @@ -2001,7 +2015,7 @@ trait Trees { self: Universe => */ implicit val LiteralTag: ClassTag[Literal] - /** The constructor/deconstructor for `Literal` instances. + /** The constructor/extractor for `Literal` instances. * @group Extractors */ val Literal: LiteralExtractor @@ -2040,7 +2054,7 @@ trait Trees { self: Universe => */ implicit val AnnotatedTag: ClassTag[Annotated] - /** The constructor/deconstructor for `Annotated` instances. + /** The constructor/extractor for `Annotated` instances. * @group Extractors */ val Annotated: AnnotatedExtractor @@ -2080,7 +2094,7 @@ trait Trees { self: Universe => */ implicit val SingletonTypeTreeTag: ClassTag[SingletonTypeTree] - /** The constructor/deconstructor for `SingletonTypeTree` instances. + /** The constructor/extractor for `SingletonTypeTree` instances. * @group Extractors */ val SingletonTypeTree: SingletonTypeTreeExtractor @@ -2117,7 +2131,7 @@ trait Trees { self: Universe => */ implicit val SelectFromTypeTreeTag: ClassTag[SelectFromTypeTree] - /** The constructor/deconstructor for `SelectFromTypeTree` instances. + /** The constructor/extractor for `SelectFromTypeTree` instances. * @group Extractors */ val SelectFromTypeTree: SelectFromTypeTreeExtractor @@ -2158,7 +2172,7 @@ trait Trees { self: Universe => */ implicit val CompoundTypeTreeTag: ClassTag[CompoundTypeTree] - /** The constructor/deconstructor for `CompoundTypeTree` instances. + /** The constructor/extractor for `CompoundTypeTree` instances. * @group Extractors */ val CompoundTypeTree: CompoundTypeTreeExtractor @@ -2194,7 +2208,7 @@ trait Trees { self: Universe => */ implicit val AppliedTypeTreeTag: ClassTag[AppliedTypeTree] - /** The constructor/deconstructor for `AppliedTypeTree` instances. + /** The constructor/extractor for `AppliedTypeTree` instances. * @group Extractors */ val AppliedTypeTree: AppliedTypeTreeExtractor @@ -2233,7 +2247,7 @@ trait Trees { self: Universe => */ implicit val TypeBoundsTreeTag: ClassTag[TypeBoundsTree] - /** The constructor/deconstructor for `TypeBoundsTree` instances. + /** The constructor/extractor for `TypeBoundsTree` instances. * @group Extractors */ val TypeBoundsTree: TypeBoundsTreeExtractor @@ -2276,7 +2290,7 @@ trait Trees { self: Universe => */ implicit val ExistentialTypeTreeTag: ClassTag[ExistentialTypeTree] - /** The constructor/deconstructor for `ExistentialTypeTree` instances. + /** The constructor/extractor for `ExistentialTypeTree` instances. * @group Extractors */ val ExistentialTypeTree: ExistentialTypeTreeExtractor @@ -2319,7 +2333,7 @@ trait Trees { self: Universe => */ implicit val TypeTreeTag: ClassTag[TypeTree] - /** The constructor/deconstructor for `TypeTree` instances. + /** The constructor/extractor for `TypeTree` instances. * @group Extractors */ val TypeTree: TypeTreeExtractor @@ -2912,7 +2926,7 @@ trait Trees { self: Universe => Modifiers(flags, privateWithin, f(annotations)) } - /** The constructor/deconstructor for `Modifiers` instances. + /** The constructor/extractor for `Modifiers` instances. * @group Traversal */ val Modifiers: ModifiersCreator diff --git a/src/reflect/scala/reflect/api/TypeCreator.scala b/src/reflect/scala/reflect/api/TypeCreator.scala index 9c386f2939..24271cb48d 100644 --- a/src/reflect/scala/reflect/api/TypeCreator.scala +++ b/src/reflect/scala/reflect/api/TypeCreator.scala @@ -4,6 +4,8 @@ package api /** A mirror-aware factory for types. * * This class is used internally by Scala Reflection, and is not recommended for use in client code. + * + * @group ReflectionAPI */ abstract class TypeCreator { def apply[U <: Universe with Singleton](m: scala.reflect.api.Mirror[U]): U # Type diff --git a/src/reflect/scala/reflect/api/TypeTags.scala b/src/reflect/scala/reflect/api/TypeTags.scala index 812d5199fc..083a495c30 100644 --- a/src/reflect/scala/reflect/api/TypeTags.scala +++ b/src/reflect/scala/reflect/api/TypeTags.scala @@ -10,13 +10,6 @@ package api import java.lang.{ Class => jClass } import scala.language.implicitConversions -/* - * TODO - * add @see to docs about universes - * [Eugene++] also mention sensitivity to prefixes, i.e. that rb.TypeTag is different from ru.TypeTag - * [Chris++] tag.in(some mirror) or expr.in(some mirror) (does not work for tag and exprs in macros) - * Backwards compat item1: [Eugene++] it might be useful, though, to guard against abstractness of the incoming type. - */ /** * A `TypeTag[T]` encapsulates the runtime type representation of some type `T`. * Like [[scala.reflect.Manifest]], the prime use case of `TypeTag`s is to give access @@ -95,7 +88,7 @@ import scala.language.implicitConversions * scala> paramInfo(List(1, 2)) * type of List(1, 2) has type arguments List(Int) * }}} - * + * * === `WeakTypeTag`s === * *`WeakTypeTag[T]` generalizes `TypeTag[T]`. Unlike a regular `TypeTag`, components of @@ -154,7 +147,7 @@ import scala.language.implicitConversions * [[http://docs.scala-lang.org/overviews/reflection/typetags-manifests.html Reflection Guide: TypeTags]] * * @see [[scala.reflect.ClassTag]], [[scala.reflect.api.TypeTags#TypeTag]], [[scala.reflect.api.TypeTags#WeakTypeTag]] - * @group TypeTags Type Tags + * @group ReflectionAPI */ trait TypeTags { self: Universe => @@ -196,16 +189,12 @@ trait TypeTags { self: Universe => */ def tpe: Type - // TODO how do I doc this? override def canEqual(x: Any) = x.isInstanceOf[WeakTypeTag[_]] - // TODO how do I doc this? override def equals(x: Any) = x.isInstanceOf[WeakTypeTag[_]] && this.mirror == x.asInstanceOf[WeakTypeTag[_]].mirror && this.tpe == x.asInstanceOf[WeakTypeTag[_]].tpe - // TODO how do I doc this? override def hashCode = mirror.hashCode * 31 + tpe.hashCode - // TODO how do I doc this? override def toString = "WeakTypeTag[" + tpe + "]" } @@ -279,16 +268,12 @@ trait TypeTags { self: Universe => */ override def in[U <: Universe with Singleton](otherMirror: scala.reflect.api.Mirror[U]): U # TypeTag[T] - /** TODO how do I doc this? */ override def canEqual(x: Any) = x.isInstanceOf[TypeTag[_]] - /** TODO how do I doc this? */ override def equals(x: Any) = x.isInstanceOf[TypeTag[_]] && this.mirror == x.asInstanceOf[TypeTag[_]].mirror && this.tpe == x.asInstanceOf[TypeTag[_]].tpe - /** TODO how do I doc this? */ override def hashCode = mirror.hashCode * 31 + tpe.hashCode - /** TODO how do I doc this? */ override def toString = "TypeTag[" + tpe + "]" } diff --git a/src/reflect/scala/reflect/api/Types.scala b/src/reflect/scala/reflect/api/Types.scala index ab165a13b7..f3201ae328 100644 --- a/src/reflect/scala/reflect/api/Types.scala +++ b/src/reflect/scala/reflect/api/Types.scala @@ -7,66 +7,46 @@ 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, - * its erasure and so on. Types also provide operation to test for type conformance or euqivalence or for widening. + * (methods, fields, type parameters, nested classes, traits, etc.) either declared directly or inherited, its base types, + * its erasure and so on. Types also provide operations to test for type conformance or equivalence or for widening. * - * === Instantiating types === + * To instantiate a type, most of the time, the [[scala.reflect.api.TypeTags#typeOf]] method can be used. It takes + * a type argument and produces a `Type` instance which represents that argument. For example: * - * 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. - * 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.TypeTags#TypeTag]] - * context bound. See [[scala.reflect.api.TypeTags the type tags page]] for details. + * {{{ + * scala> typeOf[List[Int]] + * res0: reflect.runtime.universe.Type = scala.List[Int] + * }}} * - * Finally, types can be instantiated manually using factory methods such as `typeRef` or `polyType`. - * This is necessary only in cases when `typeOf` or `typeTag` cannot be applied because the type cannot be spelt out - * in a Scala snippet, usually when writing macros. Manual construction requires deep knowledge of Scala compiler internals - * and should be avoided if possible. + * In this example, a [[scala.reflect.api.Types#TypeRef]] is returned, which corresponds to the type constructor `List` + * applied to the type argument `Int`. * - * === Using types === + * ''Note:'' Method `typeOf` does not work for types with type parameters, such as `typeOf[List[A]]` where `A` is + * a type parameter. In this case, use [[scala.reflect.api.TypeTags#weakTypeOf]] instead. * - * Common operations on types are querying them for inner declarations or type conformance tests. + * For other ways to instantiate types, see the [[http://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html corresponding section of the Reflection Guide]]. * - * 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` + * === Common Operations on Types === * - * 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. + * Types are typically used for type conformance tests or are queried for declarations of members or inner types. * - * 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[_]]`. + * - '''Subtyping Relationships''' can be tested using `<:<` and `weak_<:<`. + * - '''Type Equality''' can be checked with `=:=`. It's important to note that `==` should not be used to compare types for equality-- `==` can't check for type equality in the presence of type aliases, while `=:=` can. * - * === Exploring types === + * Types can be queried for members and declarations by using the `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 do: * * {{{ - * scala> import scala.reflect.runtime.universe._ - * import scala.reflect.runtime.universe._ - * - * scala> typeOf[List[_]].members.sorted take 5 foreach println - * constructor List - * method companion - * method :: - * 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> test(2) - * res0 @ 3fc80fae: String = I've been called for an x typed as Int - * - * scala> test(List(2, "x")) - * res1 @ 10139edf: String = I've been called for an x typed as List[Any] + * scala> typeOf[List[_]].member("map": TermName) + * res1: reflect.runtime.universe.Symbol = method map * }}} * + * For more information about `Type`s, see the [[http://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html Reflection Guide: Symbols, Trees, and Types]] + * * @groupname TypeCreators Types - Creation * @groupname TypeOps Types - Operations + * @group ReflectionAPI * * @contentDiagram hideNodes "*Api" */ @@ -174,7 +154,7 @@ trait Types { self: Universe => */ def baseClasses: List[Symbol] - /** The least type instance of given class which is a supertype + /** The least type instance of given class which is a super-type * of this type. Example: * {{{ * class D[T] @@ -185,15 +165,15 @@ trait Types { self: Universe => def baseType(clazz: Symbol): Type /** This type as seen from prefix `pre` and class `clazz`. This means: - * Replace all thistypes of `clazz` or one of its subclasses + * Replace all `ThisType`s of `clazz` or one of its subclasses * by `pre` and instantiate all parameters by arguments of `pre`. - * Proceed analogously for thistypes referring to outer classes. + * Proceed analogously for `ThisType`s referring to outer classes. * * Example: * {{{ * class D[T] { def m: T } * class C extends p.D[Int] - * T.asSeenFrom(ThisType(C), D) (where D is owner of m) + * T.asSeenFrom(ThisType(C), D) // (where D is the owner of m) * = Int * }}} */ @@ -282,7 +262,7 @@ trait Types { self: Universe => */ implicit val ThisTypeTag: ClassTag[ThisType] - /** The constructor/deconstructor for `ThisType` instances. + /** The constructor/extractor for `ThisType` instances. * @group Extractors */ val ThisType: ThisTypeExtractor @@ -326,7 +306,7 @@ trait Types { self: Universe => */ implicit val SingleTypeTag: ClassTag[SingleType] - /** The constructor/deconstructor for `SingleType` instances. + /** The constructor/extractor for `SingleType` instances. * @group Extractors */ val SingleType: SingleTypeExtractor @@ -371,7 +351,7 @@ trait Types { self: Universe => */ implicit val SuperTypeTag: ClassTag[SuperType] - /** The constructor/deconstructor for `SuperType` instances. + /** The constructor/extractor for `SuperType` instances. * @group Extractors */ val SuperType: SuperTypeExtractor @@ -416,7 +396,7 @@ trait Types { self: Universe => */ implicit val ConstantTypeTag: ClassTag[ConstantType] - /** The constructor/deconstructor for `ConstantType` instances. + /** The constructor/extractor for `ConstantType` instances. * @group Extractors */ val ConstantType: ConstantTypeExtractor @@ -460,7 +440,7 @@ trait Types { self: Universe => */ implicit val TypeRefTag: ClassTag[TypeRef] - /** The constructor/deconstructor for `TypeRef` instances. + /** The constructor/extractor for `TypeRef` instances. * @group Extractors */ val TypeRef: TypeRefExtractor @@ -525,7 +505,7 @@ trait Types { self: Universe => */ implicit val RefinedTypeTag: ClassTag[RefinedType] - /** The constructor/deconstructor for `RefinedType` instances. + /** The constructor/extractor for `RefinedType` instances. * @group Extractors */ val RefinedType: RefinedTypeExtractor @@ -577,7 +557,7 @@ trait Types { self: Universe => */ implicit val ClassInfoTypeTag: ClassTag[ClassInfoType] - /** The constructor/deconstructor for `ClassInfoType` instances. + /** The constructor/extractor for `ClassInfoType` instances. * @group Extractors */ val ClassInfoType: ClassInfoTypeExtractor @@ -620,7 +600,7 @@ trait Types { self: Universe => */ implicit val MethodTypeTag: ClassTag[MethodType] - /** The constructor/deconstructor for `MethodType` instances. + /** The constructor/extractor for `MethodType` instances. * @group Extractors */ val MethodType: MethodTypeExtractor @@ -670,7 +650,7 @@ trait Types { self: Universe => */ implicit val NullaryMethodTypeTag: ClassTag[NullaryMethodType] - /** The constructor/deconstructor for `NullaryMethodType` instances. + /** The constructor/extractor for `NullaryMethodType` instances. * @group Extractors */ val NullaryMethodType: NullaryMethodTypeExtractor @@ -706,7 +686,7 @@ trait Types { self: Universe => */ implicit val PolyTypeTag: ClassTag[PolyType] - /** The constructor/deconstructor for `PolyType` instances. + /** The constructor/extractor for `PolyType` instances. * @group Extractors */ val PolyType: PolyTypeExtractor @@ -746,7 +726,7 @@ trait Types { self: Universe => */ implicit val ExistentialTypeTag: ClassTag[ExistentialType] - /** The constructor/deconstructor for `ExistentialType` instances. + /** The constructor/extractor for `ExistentialType` instances. * @group Extractors */ val ExistentialType: ExistentialTypeExtractor @@ -787,7 +767,7 @@ trait Types { self: Universe => */ implicit val AnnotatedTypeTag: ClassTag[AnnotatedType] - /** The constructor/deconstructor for `AnnotatedType` instances. + /** The constructor/extractor for `AnnotatedType` instances. * @group Extractors */ val AnnotatedType: AnnotatedTypeExtractor @@ -838,7 +818,7 @@ trait Types { self: Universe => */ implicit val TypeBoundsTag: ClassTag[TypeBounds] - /** The constructor/deconstructor for `TypeBounds` instances. + /** The constructor/extractor for `TypeBounds` instances. * @group Extractors */ val TypeBounds: TypeBoundsExtractor @@ -895,7 +875,7 @@ trait Types { self: Universe => */ implicit val BoundedWildcardTypeTag: ClassTag[BoundedWildcardType] - /** The constructor/deconstructor for `BoundedWildcardType` instances. + /** The constructor/extractor for `BoundedWildcardType` instances. * @group Extractors */ val BoundedWildcardType: BoundedWildcardTypeExtractor diff --git a/src/reflect/scala/reflect/api/Universe.scala b/src/reflect/scala/reflect/api/Universe.scala index 068ab94a4c..4928b8bb38 100644 --- a/src/reflect/scala/reflect/api/Universe.scala +++ b/src/reflect/scala/reflect/api/Universe.scala @@ -7,7 +7,7 @@ package api * `Universe` provides a complete set of reflection operations which make it possible for one * to reflectively inspect Scala type relations, such as membership or subtyping. * - * [[scala.reflect.api.Universe]] has two specialized sub-universes for different scenarios. + * [[scala.reflect.api.Universe]] has two specialized sub-universes for different scenarios. * [[scala.reflect.api.JavaUniverse]] adds operations that link symbols and types to the underlying * classes and runtime values of a JVM instance-- this can be thought of as the `Universe` that * should be used for all typical use-cases of Scala reflection. [[scala.reflect.macros.Universe]] @@ -26,16 +26,16 @@ package api * - [[scala.reflect.api.FlagSets#FlagSet FlagSet]] represent sets of flags that apply to symbols and * definition trees * - [[scala.reflect.api.Constants#Constant Constants]] represent compile-time constants. - * - * To obtain a `Universe` to use with Scala runtime reflection, simply make sure to use or import + * + * To obtain a `Universe` to use with Scala runtime reflection, simply make sure to use or import * `scala.reflect.runtime.universe._` * {{{ * scala> import scala.reflect.runtime.universe._ * import scala.reflect.runtime.universe._ - * + * * scala> typeOf[List[Int]] * res0: reflect.runtime.universe.Type = scala.List[Int] - * + * * scala> typeOf[Either[String, Int]] * res1: reflect.runtime.universe.Type = scala.Either[String,Int] * }}} @@ -52,6 +52,7 @@ package api * For more information about `Universe`s, see the [[http://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html Reflection Guide: Universes]] * * @groupprio Universe -1 + * @group ReflectionAPI * * @contentDiagram hideNodes "*Api" */ diff --git a/src/reflect/scala/reflect/api/package.scala b/src/reflect/scala/reflect/api/package.scala index 68466b9f09..dbda84dd0e 100644 --- a/src/reflect/scala/reflect/api/package.scala +++ b/src/reflect/scala/reflect/api/package.scala @@ -19,9 +19,10 @@ import scala.reflect.api.{Universe => ApiUniverse} * - [[scala.reflect.api.Mirrors]] * - [[scala.reflect.api.Universe]] * - * For more information about Scala Reflection, see the + * For more information about Scala Reflection, see the * [[http://docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] * + * @groupname ReflectionAPI Scala Reflection API * @groupprio API 9 * @groupprio Extractors 10 * @groupprio Tags 11 diff --git a/src/reflect/scala/reflect/macros/TreeBuilder.scala b/src/reflect/scala/reflect/macros/TreeBuilder.scala index 362b35686c..204dc40858 100644 --- a/src/reflect/scala/reflect/macros/TreeBuilder.scala +++ b/src/reflect/scala/reflect/macros/TreeBuilder.scala @@ -53,25 +53,18 @@ abstract class TreeBuilder { */ def mkMethodCall(receiver: Symbol, methodName: Name, targs: List[Type], args: List[Tree]): Tree - /** TODO how to refer to the main `mkMethodCall`? */ def mkMethodCall(method: Symbol, targs: List[Type], args: List[Tree]): Tree - /** TODO how to refer to the main `mkMethodCall`? */ def mkMethodCall(method: Symbol, args: List[Tree]): Tree - /** TODO how to refer to the main `mkMethodCall`? */ def mkMethodCall(target: Tree, args: List[Tree]): Tree - /** TODO how to refer to the main `mkMethodCall`? */ def mkMethodCall(receiver: Symbol, methodName: Name, args: List[Tree]): Tree - /** TODO how to refer to the main `mkMethodCall`? */ def mkMethodCall(receiver: Tree, method: Symbol, targs: List[Type], args: List[Tree]): Tree - /** TODO how to refer to the main `mkMethodCall`? */ def mkMethodCall(target: Tree, targs: List[Type], args: List[Tree]): Tree - /** TODO how to refer to the main `mkMethodCall`? */ def mkNullaryCall(method: Symbol, targs: List[Type]): Tree /** A tree that refers to the runtime reflexive universe, ``scala.reflect.runtime.universe''. */ -- cgit v1.2.3