diff options
author | Josh Suereth <Joshua.Suereth@gmail.com> | 2012-11-02 10:35:47 -0700 |
---|---|---|
committer | Josh Suereth <Joshua.Suereth@gmail.com> | 2012-11-02 10:35:47 -0700 |
commit | f8ed076e251ff8b6e2b1d27f8c8a0dde2117308d (patch) | |
tree | 86e6126f78ffe707684e109c706bd51c2350052e /src | |
parent | 59149579aec4b3d26a4cb849d80535a36b90ad30 (diff) | |
parent | 093b8e1b6fdb88eab0739b21b4e3b4815be0795f (diff) | |
download | scala-f8ed076e251ff8b6e2b1d27f8c8a0dde2117308d.tar.gz scala-f8ed076e251ff8b6e2b1d27f8c8a0dde2117308d.tar.bz2 scala-f8ed076e251ff8b6e2b1d27f8c8a0dde2117308d.zip |
Merge pull request #1558 from heathermiller/doc/reflection-errata
API docs: reflection fixes, AnyVal/Any documentation additions, errata
Diffstat (limited to 'src')
48 files changed, 459 insertions, 279 deletions
diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css b/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css index 6fb7953724..b066027f04 100644 --- a/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css +++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css @@ -824,3 +824,25 @@ div.fullcomment dl.paramcmts > dd { color: #4C4C4C; font-weight: bold; }*/ + +.badge { + display: inline-block; + padding: 2px 4px; + font-size: 11.844px; + font-weight: bold; + line-height: 14px; + color: #ffffff; + text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25); + white-space: nowrap; + vertical-align: baseline; + background-color: #999999; + padding-right: 9px; + padding-left: 9px; + -webkit-border-radius: 9px; + -moz-border-radius: 9px; + border-radius: 9px; +} + +.badge-red { + background-color: #b94a48; +} diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type.png b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type.png Binary files differindex 366ec4e992..6c6e1fe2f5 100644 --- a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type.png +++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type.png diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_big.png b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_big.png Binary files differindex df0dc118bf..04c8794e92 100644 --- a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_big.png +++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_big.png diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_diagram.png b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_diagram.png Binary files differindex d6fbb84ff2..d8152529fd 100644 --- a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_diagram.png +++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_diagram.png diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_to_object_big.png b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_to_object_big.png Binary files differindex 1bd2833a63..ef2615bacc 100644 --- a/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_to_object_big.png +++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/type_to_object_big.png diff --git a/src/library-aux/scala/Any.scala b/src/library-aux/scala/Any.scala index 031b7d9d8c..07a9ffa8d5 100644 --- a/src/library-aux/scala/Any.scala +++ b/src/library-aux/scala/Any.scala @@ -10,6 +10,25 @@ package scala /** Class `Any` is the root of the Scala class hierarchy. Every class in a Scala * execution environment inherits directly or indirectly from this class. + * + * Starting with Scala 2.10 it is possible to directly extend `Any` using ''universal traits''. + * A ''universal trait'' is a trait that extends `Any`, only has `def`s as members, and does no initialization. + * + * The main use case for universal traits is to allow basic inheritance of methods for [[scala.AnyVal value classes]]. + * For example, + * + * {{{ + * trait Printable extends Any { + * def print(): Unit = println(this) + * } + * class Wrapper(val underlying: Int) extends AnyVal with Printable + * + * val w = new Wrapper(3) + * w.print() + * }}} + * + * See the [[http://docs.scala-lang.org/sips/pending/value-classes.html value classes guide]] for more + * details on the interplay of universal traits and value classes. */ abstract class Any { /** Compares the receiver object (`this`) with the argument object (`that`) for equivalence. diff --git a/src/library/scala/AnyVal.scala b/src/library/scala/AnyVal.scala index d637527b30..ebdc963946 100644 --- a/src/library/scala/AnyVal.scala +++ b/src/library/scala/AnyVal.scala @@ -9,8 +9,8 @@ package scala /** `AnyVal` is the root class of all ''value types'', which describe values - * not implemented as objects in the underlying host system. The value classes - * are specified in SLS 12.2. + * not implemented as objects in the underlying host system. Value classes + * are specified in Scala Language Specification, section 12.2. * * The standard implementation includes nine `AnyVal` subtypes: * @@ -21,9 +21,36 @@ package scala * * Other groupings: * - * The ''subrange types'' are [[scala.Byte]], [[scala.Short]], and [[scala.Char]]. - * The ''integer types'' include the subrange types as well as [[scala.Int]] and [[scala.Long]]. - * The ''floating point types'' are [[scala.Float]] and [[scala.Double]]. + * - The ''subrange types'' are [[scala.Byte]], [[scala.Short]], and [[scala.Char]]. + * - The ''integer types'' include the subrange types as well as [[scala.Int]] and [[scala.Long]]. + * - The ''floating point types'' are [[scala.Float]] and [[scala.Double]]. + * + * Prior to Scala 2.10, `AnyVal` was a sealed trait. Beginning with Scala 2.10, + * however, it is possible to define a subclass of `AnyVal` called a ''user-defined value class'' + * which is treated specially by the compiler. Properly-defined user value classes provide a way + * to improve performance on user-defined types by avoiding object allocation at runtime, and by + * replacing virtual method invocations with static method invocations. + * + * User-defined value classes which avoid object allocation... + * + * - must have a single, public `val` parameter that is the underlying runtime representation. + * - can define `def`s, but no `val`s, `var`s, or nested `traits`s, `class`es or `object`s. + * - typically extend no other trait apart from `AnyVal`. + * - cannot be used in type tests or pattern matching. + * - may not override `equals` or `hashCode` methods. + * + * A minimal example: + * {{{ + * class Wrapper(val underlying: Int) extends AnyVal { + * def foo: Wrapper = new Wrapper(underlying * 19) + * } + * }}} + * + * It's important to note that user-defined value classes are limited, and in some circumstances, + * still must allocate a value class instance at runtime. These limitations and circumstances are + * explained in greater detail in the [[http://docs.scala-lang.org/overviews/core/value-classes.html Value Classes Guide]] + * as well as in [[http://docs.scala-lang.org/sips/pending/value-classes.html SIP-15: Value Classes]], + * the Scala Improvement Proposal. */ abstract class AnyVal extends Any with NotNull { def getClass(): Class[_ <: AnyVal] = null diff --git a/src/library/scala/concurrent/Future.scala b/src/library/scala/concurrent/Future.scala index 111900e7bc..f308b674bb 100644 --- a/src/library/scala/concurrent/Future.scala +++ b/src/library/scala/concurrent/Future.scala @@ -58,7 +58,7 @@ import scala.reflect.ClassTag * Instead, the future is completed with a ExecutionException with one of the exceptions above * as the cause. * If a future is failed with a `scala.runtime.NonLocalReturnControl`, - * it is completed with a value instead from that throwable instead instead. + * it is completed with a value from that throwable instead. * * @define nonDeterministic * Note: using this method yields nondeterministic dataflow programs. diff --git a/src/reflect/scala/reflect/api/Annotations.scala b/src/reflect/scala/reflect/api/Annotations.scala index fb353a5520..09eaf7afb4 100644 --- a/src/reflect/scala/reflect/api/Annotations.scala +++ b/src/reflect/scala/reflect/api/Annotations.scala @@ -3,7 +3,10 @@ package api import scala.collection.immutable.ListMap -/** This trait provides annotation support for the reflection API. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * This trait provides annotation support for the reflection API. * * The API distinguishes between two kinds of annotations: * @@ -13,9 +16,9 @@ import scala.collection.immutable.ListMap * is automatically added as a subclass to every Java annotation.</li> * <li>''Scala annotations'': annotations on definitions or types produced by the Scala compiler.</li> * </ul> - * - * When a Scala annotation that inherits from [[scala.annotation.StaticAnnotation]] or [[scala.annotation.ClassfileAnnotation]] is compiled, - * it is stored as special attributes in the corresponding classfile, and not as a Java annotation. Note that subclassing + * + * 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 @@ -29,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 => @@ -45,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 @@ -102,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 @@ -137,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 @@ -172,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 a92fc5cbb3..4a8a2868cc 100644 --- a/src/reflect/scala/reflect/api/Constants.scala +++ b/src/reflect/scala/reflect/api/Constants.scala @@ -7,6 +7,8 @@ package scala.reflect package api /** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * * According to the section 6.24 "Constant Expressions" of the Scala language specification, * certain expressions (dubbed ''constant expressions'') can be evaluated by the Scala compiler at compile-time. * @@ -82,6 +84,7 @@ package api * }}} * * @contentDiagram hideNodes "*Api" + * @group ReflectionAPI */ trait Constants { self: Universe => @@ -186,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 45bfddb55d..eeef94598c 100644 --- a/src/reflect/scala/reflect/api/Exprs.scala +++ b/src/reflect/scala/reflect/api/Exprs.scala @@ -8,7 +8,10 @@ package api import scala.reflect.runtime.{universe => ru} -/** A trait that defines strongly-typed tree wrappers and operations on them for use in Scala Reflection. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A trait that defines strongly-typed tree wrappers and operations on them for use in Scala Reflection. * * `Expr` wraps an abstract syntax tree ([[scala.reflect.api.Trees#Tree]]) and tags it with its type ([[scala.reflect.api.Types#Type]]). * @@ -24,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 => @@ -103,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 a7d1ca05a6..4357aec9c9 100644 --- a/src/reflect/scala/reflect/api/FlagSets.scala +++ b/src/reflect/scala/reflect/api/FlagSets.scala @@ -4,6 +4,8 @@ package api import scala.language.implicitConversions /** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * * The trait that defines flag sets and operations on them. * * `Flag`s are used to provide modifiers for abstract syntax trees that represent definitions @@ -19,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: * {{{ @@ -34,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 @@ -45,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 4286b2b45c..afc4f2f25d 100644 --- a/src/reflect/scala/reflect/api/Importers.scala +++ b/src/reflect/scala/reflect/api/Importers.scala @@ -1,17 +1,21 @@ package scala.reflect package api -/** This trait provides support for importers, a facility to migrate reflection artifacts between universes. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * 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 @@ -52,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 df099006b5..b678033e1a 100644 --- a/src/reflect/scala/reflect/api/JavaMirrors.scala +++ b/src/reflect/scala/reflect/api/JavaMirrors.scala @@ -1,7 +1,10 @@ package scala.reflect package api -/** A refinement of [[scala.reflect.api.Mirror]] for runtime reflection using JVM classloaders. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A refinement of [[scala.reflect.api.Mirror]] for runtime reflection using JVM classloaders. * * This refinement equips mirrors with reflection capabilities for the JVM. `JavaMirror` can * convert Scala reflection artifacts (symbols and types) into Java reflection artifacts (classes) @@ -12,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 f83692034f..04d091ee9d 100644 --- a/src/reflect/scala/reflect/api/JavaUniverse.scala +++ b/src/reflect/scala/reflect/api/JavaUniverse.scala @@ -1,13 +1,18 @@ package scala.reflect package api -/** A refinement of [[scala.reflect.api.Universe]] for runtime reflection using JVM classloaders. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A refinement of [[scala.reflect.api.Universe]] for runtime reflection using JVM classloaders. * * 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 [[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 b1290cc02e..1223326d7c 100644 --- a/src/reflect/scala/reflect/api/Mirror.scala +++ b/src/reflect/scala/reflect/api/Mirror.scala @@ -2,16 +2,19 @@ package scala.reflect package api /** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * * The base class for all mirrors. * * See [[scala.reflect.api.Mirrors]] or [[docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] * 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 cc1b9762cb..d0d8a37584 100644 --- a/src/reflect/scala/reflect/api/Mirrors.scala +++ b/src/reflect/scala/reflect/api/Mirrors.scala @@ -1,7 +1,10 @@ package scala.reflect package api -/** This trait provides support for Mirrors in the Scala Reflection API. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * This trait provides support for Mirrors in the Scala Reflection API. * * `Mirror`s are a central part of Scala Reflection. All information provided by * reflection is made accessible through `Mirror`s. Depending on the type of information @@ -14,13 +17,13 @@ package api * The two flavors of mirrors: * * <ul> - * <li>```“Classloader” mirrors```. These mirrors translate names to symbols + * <li>'''“Classloader” mirrors'''. These mirrors translate names to symbols * (via methods `staticClass`/`staticModule`/`staticPackage`).</li> - * <li>```"Invoker” mirrors```. These mirrors implement reflective invocations + * <li>'''"Invoker” mirrors'''. These mirrors implement reflective invocations * (via methods `MethodMirror.apply`, `FieldMirror.get`, etc). These "invoker" * mirrors are the types of mirrors that are most commonly used.</li> * </ul> - * + * * === Compile-time Mirrors === * Compile-time `Mirror`s make use of only classloader `Mirror`s to load `Symbol`s * by name. @@ -50,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. @@ -59,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]], @@ -202,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 02eb79f8ed..7c12f180a8 100644 --- a/src/reflect/scala/reflect/api/Names.scala +++ b/src/reflect/scala/reflect/api/Names.scala @@ -1,21 +1,29 @@ package scala.reflect package api -/** This trait defines Names (a Scala reflection concept) and operations on them. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> * - * 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. + * This trait defines `Name`s in Scala Reflection, and operations on them. * - * === Examples === + * 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. * - * 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. + * To search for the `map` method (which is a term) declared in the `List` class, one can do: * - * See the [[docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for more about Scala Reflection. + * {{{ + * scala> typeOf[List[_]].member(newTermName("map")) + * res0: reflect.runtime.universe.Symbol = method map + * }}} + * + * 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 61d643b449..63c67627a3 100644 --- a/src/reflect/scala/reflect/api/Position.scala +++ b/src/reflect/scala/reflect/api/Position.scala @@ -3,44 +3,18 @@ package api 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. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> * - * A position indicates the [[source source file]] and an [[point offset]]. A position may be - * undefined, which means it's pointing to the [[Positions#NoPosition]] element. + * 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. * - * <b>Please note that this trait may be refactored in future versions of the Scala reflection API.</b> + * <b>Please note that this trait may be refactored in future versions of the Scala reflection API.</b> * - * @see [[http://docs.scala-lang.org/overviews/reflection/names-exprs-scopes-more.html]] - * - * The compiler adds more information to positions, such a ranges in the source file and defines different types of - * positions depending on how a symbol or tree node was generated. The guide fully describes compiler-generated positions. - * - * - INV1: A tree with an offset position never contains a child - * with a range position - * - INV2: If the child of a tree with a range position also has a range position, - * then the child's range is contained in the parent's range. - * - INV3: Opaque range positions of children of the same node are non-overlapping - * (this means their overlap is at most a single point). - * - * The following tests are useful on positions: - * `pos.isDefined` true if position is not a NoPosition, - * `pos.isRange` true if position is a range, - * `pos.isOpaqueRange` true if position is an opaque range, - * - * There are also convenience methods, such as - * `pos.startOrPoint`, - * `pos.endOrPoint`, - * `pos.pointOrElse(default)`. - * These are less strict about the kind of position on which they can be applied. - * - * The following conversion methods are often used: - * `pos.focus` converts a range position to an offset position, keeping its point; - * returns all other positions unchanged, - * `pos.makeTransparent` converts an opaque range position into a transparent one. - * returns all other positions unchanged. + * 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 { @@ -70,7 +44,7 @@ trait Position extends Attachments { def isTransparent: Boolean /** Is this position a non-transparent range position? */ - def isOpaqueRange: Boolean + def isOpaqueRange: Boolean /** If opaque range, make this position transparent. */ def makeTransparent: Pos diff --git a/src/reflect/scala/reflect/api/Positions.scala b/src/reflect/scala/reflect/api/Positions.scala index 8d8a0081cc..87f00fdb88 100644 --- a/src/reflect/scala/reflect/api/Positions.scala +++ b/src/reflect/scala/reflect/api/Positions.scala @@ -1,11 +1,15 @@ package scala.reflect package api -/** This trait defines the concept of positions and operations on them. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> * - * @see [[scala.reflect.api.Position]] + * This trait defines the concept of positions and operations on them. * - * @contentDiagram hideNodes "*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 1e8161aeef..85ddcc6523 100644 --- a/src/reflect/scala/reflect/api/Printers.scala +++ b/src/reflect/scala/reflect/api/Printers.scala @@ -3,14 +3,17 @@ package api import java.io.{ PrintWriter, StringWriter } -/** Utilities for nicely printing [[scala.reflect.api.Trees]] and [[scala.reflect.api.Types]]. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> * - * === Printing Trees === - * The method `show` displays the "prettified" representation of reflection artifacts. - * This representation provides one with the desugared Java representation of Scala code. - * For example: + * Utilities for nicely printing [[scala.reflect.api.Trees]] and [[scala.reflect.api.Types]]. * - * {{{ + * === Printing Trees === + * The method `show` displays the "prettified" representation of reflection artifacts. + * This representation provides one with the desugared Java representation of Scala code. + * For example: + * + * {{{ * scala> import scala.reflect.runtime.universe._ * import scala.reflect.runtime.universe._ * @@ -30,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. @@ -54,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 * {{{ @@ -89,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._ @@ -116,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 80683c8e76..7f9799393c 100644 --- a/src/reflect/scala/reflect/api/Scopes.scala +++ b/src/reflect/scala/reflect/api/Scopes.scala @@ -1,19 +1,24 @@ package scala.reflect package api -/** This trait provides support for scopes in the reflection API. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> * - * A scope object generally maps names to symbols available in a corresponding lexical scope. - * Scopes can be nested. The base type exposed to the reflection API, however, - * only exposes a minimal interface, representing a scope as an iterable of symbols. + * This trait provides support for scopes in the reflection API. * - * For rare occasions when it is necessary to create a scope manually, - * e.g., to populate members of [[scala.reflect.api.Types#RefinedType]], - * there is the `newScopeWith` function. + * A scope object generally maps names to symbols available in a corresponding lexical scope. + * Scopes can be nested. The base type exposed to the reflection API, however, + * only exposes a minimal interface, representing a scope as an iterable of symbols. * - * 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. + * For rare occasions when it is necessary to create a scope manually, + * e.g., to populate members of [[scala.reflect.api.Types#RefinedType]], + * there is the `newScopeWith` function. + * + * 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 a31a501357..61097e3f69 100644 --- a/src/reflect/scala/reflect/api/StandardDefinitions.scala +++ b/src/reflect/scala/reflect/api/StandardDefinitions.scala @@ -5,11 +5,16 @@ package scala.reflect package api -/** All Scala standard symbols and types. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> * - * These standard definitions can accessed to using `definitions`. - * They're typically imported with a blanket import `import definitions`, and are + * All Scala standard symbols and types. + * + * 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 fc18c02706..e24bc91ced 100644 --- a/src/reflect/scala/reflect/api/StandardNames.scala +++ b/src/reflect/scala/reflect/api/StandardNames.scala @@ -11,6 +11,8 @@ package api // Otherwise you'd better not - reflection API should stay minimalistic. /** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * * Standard names are names that are essential to creating trees or to reflecting Scala artifacts. * For example, `CONSTRUCTOR` (aka `<init>` on JVM) is necessary to create and invoke constructors. * @@ -20,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 993cbd97a5..b53c700701 100644 --- a/src/reflect/scala/reflect/api/Symbols.scala +++ b/src/reflect/scala/reflect/api/Symbols.scala @@ -1,25 +1,57 @@ package scala.reflect package api -/** This trait defines symbols and operations on them. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * This trait defines symbols and operations on them. * * 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 4e43f59706..5de811578e 100644 --- a/src/reflect/scala/reflect/api/TagInterop.scala +++ b/src/reflect/scala/reflect/api/TagInterop.scala @@ -1,7 +1,12 @@ package scala.reflect package api -/** This trait provides type tag <-> manifest interoperability. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * 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 bcb1d0031f..d34fb78b89 100644 --- a/src/reflect/scala/reflect/api/Trees.scala +++ b/src/reflect/scala/reflect/api/Trees.scala @@ -5,28 +5,44 @@ package scala.reflect package api -/** This trait defines the node types used in Scala abstract syntax trees (AST) and operations on them. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> * -* All tree node types are sub types of [[scala.reflect.api.Trees#Tree Tree]]. + * This trait defines the node types used in Scala abstract syntax trees (AST) and operations on them. + * + * 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 @@ -34,6 +50,7 @@ package api * @groupprio Copying 1 * * @contentDiagram hideNodes "*Api" + * @group ReflectionAPI */ trait Trees { self: Universe => @@ -346,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 @@ -405,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 @@ -456,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 @@ -539,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 @@ -594,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 @@ -649,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 @@ -714,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 @@ -776,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 @@ -828,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 @@ -886,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 @@ -944,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 @@ -989,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 @@ -1042,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 @@ -1080,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 @@ -1121,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 @@ -1190,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 @@ -1232,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 @@ -1276,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 @@ -1318,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 @@ -1365,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 @@ -1422,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 @@ -1463,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 @@ -1501,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 @@ -1545,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 @@ -1581,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 @@ -1628,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 @@ -1694,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 @@ -1728,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 @@ -1771,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 @@ -1823,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 @@ -1864,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 @@ -1903,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 @@ -1948,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 @@ -1998,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 @@ -2037,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 @@ -2077,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 @@ -2114,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 @@ -2155,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 @@ -2191,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 @@ -2230,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 @@ -2273,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 @@ -2316,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 @@ -2909,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 7b8cf592ff..f3201ae328 100644 --- a/src/reflect/scala/reflect/api/Types.scala +++ b/src/reflect/scala/reflect/api/Types.scala @@ -1,69 +1,52 @@ package scala.reflect package api -/** A trait that defines types and operations on them. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> * - * 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. + * A trait that defines types and operations on them. * - * === Instantiating 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 operations to test for type conformance or equivalence or for widening. * - * 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. + * 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: * - * `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" */ @@ -171,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] @@ -182,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 * }}} */ @@ -279,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 @@ -323,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 @@ -368,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 @@ -413,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 @@ -457,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 @@ -522,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 @@ -574,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 @@ -617,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 @@ -667,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 @@ -703,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 @@ -743,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 @@ -784,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 @@ -835,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 @@ -892,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 7d1f5c9df1..4928b8bb38 100644 --- a/src/reflect/scala/reflect/api/Universe.scala +++ b/src/reflect/scala/reflect/api/Universe.scala @@ -2,10 +2,12 @@ package scala.reflect package api /** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * * `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]] @@ -24,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] * }}} @@ -50,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 bd9c72a839..dbda84dd0e 100644 --- a/src/reflect/scala/reflect/api/package.scala +++ b/src/reflect/scala/reflect/api/package.scala @@ -2,7 +2,10 @@ package scala.reflect import scala.reflect.api.{Universe => ApiUniverse} -/** The Scala Reflection API (located in scala-reflect.jar). +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * The Scala Reflection API (located in scala-reflect.jar). * * In Scala 2.10.0, the Scala Reflection API and its implementation have an "experimental" status. * This means that the API and the docs are not complete and can be changed in binary- and source-incompatible @@ -16,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/Aliases.scala b/src/reflect/scala/reflect/macros/Aliases.scala index 7f7ab66848..92d76f4370 100644 --- a/src/reflect/scala/reflect/macros/Aliases.scala +++ b/src/reflect/scala/reflect/macros/Aliases.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that defines shorthands for the +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A slice of [[scala.reflect.macros.Context the Scala macros context]] that defines shorthands for the * most frequently used types and functions of the underlying compiler universe. */ trait Aliases { diff --git a/src/reflect/scala/reflect/macros/Attachments.scala b/src/reflect/scala/reflect/macros/Attachments.scala index ba5ccf88f1..a77cebf415 100644 --- a/src/reflect/scala/reflect/macros/Attachments.scala +++ b/src/reflect/scala/reflect/macros/Attachments.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** Attachments provide a way to associate custom metadata with symbols and trees. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * Attachments provide a way to associate custom metadata with symbols and trees. * * Along with `symbol` and `tpe`, which represent core metadata of trees, each tree * carries the `attachments` field that can store other metadata: compiler-defined (e.g. positions) or user-defined. diff --git a/src/reflect/scala/reflect/macros/Context.scala b/src/reflect/scala/reflect/macros/Context.scala index 1f6e97adbc..aa1c1db227 100644 --- a/src/reflect/scala/reflect/macros/Context.scala +++ b/src/reflect/scala/reflect/macros/Context.scala @@ -5,7 +5,10 @@ package macros // the most lightweight context should just expose the stuff from the SIP // the full context should include all traits from scala.reflect.macros (and probably reside in scala-compiler.jar) -/** The Scala macros context. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * The Scala macros context. * * See [[scala.reflect.macros.package the overview page]] for a description of how macros work. This documentation * entry provides information on the API available to macro writers. diff --git a/src/reflect/scala/reflect/macros/Enclosures.scala b/src/reflect/scala/reflect/macros/Enclosures.scala index 41d6af94e3..c48656b366 100644 --- a/src/reflect/scala/reflect/macros/Enclosures.scala +++ b/src/reflect/scala/reflect/macros/Enclosures.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that exposes +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A slice of [[scala.reflect.macros.Context the Scala macros context]] that exposes * enclosing trees (method, class, compilation unit and currently compiled application), * the enclosing position of the macro expansion, as well as macros and implicits * that are currently in-flight. diff --git a/src/reflect/scala/reflect/macros/Evals.scala b/src/reflect/scala/reflect/macros/Evals.scala index 6aab3d5b02..37680c219b 100644 --- a/src/reflect/scala/reflect/macros/Evals.scala +++ b/src/reflect/scala/reflect/macros/Evals.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that provides +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A slice of [[scala.reflect.macros.Context the Scala macros context]] that provides * a facility to evaluate trees. */ trait Evals { diff --git a/src/reflect/scala/reflect/macros/ExprUtils.scala b/src/reflect/scala/reflect/macros/ExprUtils.scala index a9acc61735..458cde9692 100644 --- a/src/reflect/scala/reflect/macros/ExprUtils.scala +++ b/src/reflect/scala/reflect/macros/ExprUtils.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that defines shorthands for the +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A slice of [[scala.reflect.macros.Context the Scala macros context]] that defines shorthands for the * most common `Expr`-creating functions. */ trait ExprUtils { diff --git a/src/reflect/scala/reflect/macros/FrontEnds.scala b/src/reflect/scala/reflect/macros/FrontEnds.scala index 8c47202342..67b24088b5 100644 --- a/src/reflect/scala/reflect/macros/FrontEnds.scala +++ b/src/reflect/scala/reflect/macros/FrontEnds.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A slice of [[scala.reflect.macros.Context the Scala macros context]] that * provides facilities to communicate with the compiler's front end * (emit warnings, errors and other sorts of messages). */ diff --git a/src/reflect/scala/reflect/macros/Infrastructure.scala b/src/reflect/scala/reflect/macros/Infrastructure.scala index 2f3b8e8d19..99706e84fe 100644 --- a/src/reflect/scala/reflect/macros/Infrastructure.scala +++ b/src/reflect/scala/reflect/macros/Infrastructure.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A slice of [[scala.reflect.macros.Context the Scala macros context]] that * provides facilities to communicate with the compiler's infrastructure. */ trait Infrastructure { diff --git a/src/reflect/scala/reflect/macros/Names.scala b/src/reflect/scala/reflect/macros/Names.scala index 20e750b225..8bbaa5f848 100644 --- a/src/reflect/scala/reflect/macros/Names.scala +++ b/src/reflect/scala/reflect/macros/Names.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A slice of [[scala.reflect.macros.Context the Scala macros context]] that * provides functions that generate unique names. */ trait Names { diff --git a/src/reflect/scala/reflect/macros/Parsers.scala b/src/reflect/scala/reflect/macros/Parsers.scala index bf73c36b1b..93a763792c 100644 --- a/src/reflect/scala/reflect/macros/Parsers.scala +++ b/src/reflect/scala/reflect/macros/Parsers.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A slice of [[scala.reflect.macros.Context the Scala macros context]] that * exposes functions to parse strings with Scala code into trees. */ trait Parsers { diff --git a/src/reflect/scala/reflect/macros/Reifiers.scala b/src/reflect/scala/reflect/macros/Reifiers.scala index d7ee30c7d9..3db7b9af02 100644 --- a/src/reflect/scala/reflect/macros/Reifiers.scala +++ b/src/reflect/scala/reflect/macros/Reifiers.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A slice of [[scala.reflect.macros.Context the Scala macros context]] that * exposes functions to save reflection artifacts for runtime. */ trait Reifiers { diff --git a/src/reflect/scala/reflect/macros/TreeBuilder.scala b/src/reflect/scala/reflect/macros/TreeBuilder.scala index 727387c5af..204dc40858 100644 --- a/src/reflect/scala/reflect/macros/TreeBuilder.scala +++ b/src/reflect/scala/reflect/macros/TreeBuilder.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A helper available in [[scala.reflect.macros.Universe]] that defines shorthands for the +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A helper available in [[scala.reflect.macros.Universe]] that defines shorthands for the * most common tree-creating functions. */ abstract class TreeBuilder { @@ -50,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''. */ diff --git a/src/reflect/scala/reflect/macros/Typers.scala b/src/reflect/scala/reflect/macros/Typers.scala index 016a08bd01..427e7854b2 100644 --- a/src/reflect/scala/reflect/macros/Typers.scala +++ b/src/reflect/scala/reflect/macros/Typers.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** A slice of [[scala.reflect.macros.Context the Scala macros context]] that +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * A slice of [[scala.reflect.macros.Context the Scala macros context]] that * partially exposes the type checker to macro writers. */ trait Typers { diff --git a/src/reflect/scala/reflect/macros/Universe.scala b/src/reflect/scala/reflect/macros/Universe.scala index 86bc37b4c9..4e76f7c408 100644 --- a/src/reflect/scala/reflect/macros/Universe.scala +++ b/src/reflect/scala/reflect/macros/Universe.scala @@ -1,7 +1,10 @@ package scala.reflect package macros -/** The refinement of [[scala.reflect.api.Universe]] for the use by macro writers. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * The refinement of [[scala.reflect.api.Universe]] for the use by macro writers. * * 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 diff --git a/src/reflect/scala/reflect/macros/package.scala b/src/reflect/scala/reflect/macros/package.scala index 3a2f04bcf2..21d189bb25 100644 --- a/src/reflect/scala/reflect/macros/package.scala +++ b/src/reflect/scala/reflect/macros/package.scala @@ -1,6 +1,9 @@ package scala.reflect -/** The base package for Scala macros. +/** + * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span> + * + * The base package for Scala macros. * * Macros are functions that are called by the compiler during compilation. * Within these functions the programmer has access to compiler APIs exposed in [[scala.reflect.macros.Context]]. |