Skip to content

Commit 6ce5d1e

Browse files
VladUrecheVladUreche
committed
Grouping for reflection and macros
and warning cleanup
1 parent 25c3ea3 commit 6ce5d1e

24 files changed

+1046
-251
lines changed

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

Lines changed: 53 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -3,52 +3,58 @@ package api
33

44
import scala.collection.immutable.ListMap
55

6-
/** This trait provides annotation support for the reflection API.
6+
/** This trait provides annotation support for the reflection API.
77
*
88
* The API distinguishes between two kinds of annotations:
9-
* 1. ''Java annotations'': annotations on definitions produced by the Java compiler, i.e., subtypes of [[java.lang.annotation.Annotation]]
10-
* attached to program definitions. When read by Scala reflection, the [[scala.annotation.ClassfileAnnotation]] trait
11-
* is automatically added as a subclass to every Java annotation.
12-
* 2. ''Scala annotations'': annotations on definitions or types produced by the Scala compiler.
13-
*
14-
* When a Scala annotation that inherits from [[scala.annotation.StaticAnnotation]] or [[scala.annotation.ClassfileAnnotation]] is compiled,
15-
* it is stored as special attributes in the corresponding classfile, and not as a Java annotation. Note that subclassing
9+
* 1. ''Java annotations'': annotations on definitions produced by the Java compiler, i.e., subtypes of `java.lang.annotation.Annotation` attached to program definitions. When read by Scala reflection, the [[scala.annotation.ClassfileAnnotation]] trait is automatically added as a subclass to every Java annotation.
10+
* 1. ''Scala annotations'': annotations on definitions or types produced by the Scala compiler.
11+
*
12+
* When a Scala annotation that inherits from [[scala.annotation.StaticAnnotation]] or [[scala.annotation.ClassfileAnnotation]] is compiled,
13+
* it is stored as special attributes in the corresponding classfile, and not as a Java annotation. Note that subclassing
1614
* just [[scala.annotation.Annotation]] is not enough to have the corresponding metadata persisted for runtime reflection.
17-
*
15+
*
1816
* The distinction between Java and Scala annotations is manifested in the contract of [[scala.reflect.api.Annotations#Annotation]], which exposes
19-
* both `scalaArgs` and `javaArgs`. For Scala or Java annotations extending [[scala.annotation.ClassfileAnnotation]] `scalaArgs` is empty
17+
* both `scalaArgs` and `javaArgs`. For Scala or Java annotations extending [[scala.annotation.ClassfileAnnotation]] `scalaArgs` is empty
2018
* and arguments are stored in `javaArgs`. For all other Scala annotations, arguments are stored in `scalaArgs` and `javaArgs` is empty.
21-
*
19+
*
2220
* Arguments in `scalaArgs` are represented as typed trees. Note that these trees are not transformed by any phases
2321
* following the type-checker. Arguments in `javaArgs` are repesented as a map from [[scala.reflect.api.Names#Name]] to
24-
* [[scala.reflect.api.Annotations#JavaArgument]]. Instances of `JavaArgument` represent different kinds of Java annotation arguments:
22+
* [[scala.reflect.api.Annotations#JavaArgument]]. Instances of `JavaArgument` represent different kinds of Java annotation arguments:
2523
* - literals (primitive and string constants),
26-
* - arrays and
24+
* - arrays and
2725
* - nested annotations.
2826
*/
2927
trait Annotations { self: Universe =>
3028

31-
/** Information about an annotation. */
29+
/** Information about an annotation.
30+
* @template
31+
* @group Annotations
32+
*/
3233
type Annotation >: Null <: AnyRef with AnnotationApi
3334

3435
/** A tag that preserves the identity of the `Annotation` abstract type from erasure.
3536
* Can be used for pattern matching, instance tests, serialization and likes.
37+
* @group Tags
3638
*/
3739
implicit val AnnotationTag: ClassTag[Annotation]
3840

39-
/** The constructor/deconstructor for `Annotation` instances. */
41+
/** The constructor/deconstructor for `Annotation` instances.
42+
* @group Extractors
43+
*/
4044
val Annotation: AnnotationExtractor
4145

4246
/** An extractor class to create and pattern match with syntax `Annotation(tpe, scalaArgs, javaArgs)`.
4347
* Here, `tpe` is the annotation type, `scalaArgs` the payload of Scala annotations, and `javaArgs` the payload of Java annotations.
44-
*/
48+
* @group Extractors
49+
*/
4550
abstract class AnnotationExtractor {
4651
def apply(tpe: Type, scalaArgs: List[Tree], javaArgs: ListMap[Name, JavaArgument]): Annotation
4752
def unapply(ann: Annotation): Option[(Type, List[Tree], ListMap[Name, JavaArgument])]
4853
}
4954

5055
/** The API of `Annotation` instances.
5156
* The main source of information about annotations is the [[scala.reflect.api.Annotations]] page.
57+
* @group API
5258
*/
5359
trait AnnotationApi {
5460
/** The type of the annotation. */
@@ -65,27 +71,38 @@ trait Annotations { self: Universe =>
6571
def javaArgs: ListMap[Name, JavaArgument]
6672
}
6773

68-
/** A Java annotation argument */
74+
/** A Java annotation argument
75+
* @template
76+
* @group Annotations
77+
*/
6978
type JavaArgument >: Null <: AnyRef
7079

7180
/** A tag that preserves the identity of the `JavaArgument` abstract type from erasure.
7281
* Can be used for pattern matching, instance tests, serialization and likes.
82+
* @group Tags
7383
*/
7484
implicit val JavaArgumentTag: ClassTag[JavaArgument]
7585

76-
/** A literal argument to a Java annotation as `"Use X instead"` in `@Deprecated("Use X instead")`*/
86+
/** A literal argument to a Java annotation as `"Use X instead"` in `@Deprecated("Use X instead")`
87+
* @template
88+
* @group Annotations
89+
*/
7790
type LiteralArgument >: Null <: AnyRef with JavaArgument with LiteralArgumentApi
7891

7992
/** A tag that preserves the identity of the `LiteralArgument` abstract type from erasure.
8093
* Can be used for pattern matching, instance tests, serialization and likes.
94+
* @group Tags
8195
*/
8296
implicit val LiteralArgumentTag: ClassTag[LiteralArgument]
8397

84-
/** The constructor/deconstructor for `LiteralArgument` instances. */
98+
/** The constructor/deconstructor for `LiteralArgument` instances.
99+
* @group Extractors
100+
*/
85101
val LiteralArgument: LiteralArgumentExtractor
86102

87103
/** An extractor class to create and pattern match with syntax `LiteralArgument(value)`
88104
* where `value` is the constant argument.
105+
* @group Extractors
89106
*/
90107
abstract class LiteralArgumentExtractor {
91108
def apply(value: Constant): LiteralArgument
@@ -94,26 +111,33 @@ trait Annotations { self: Universe =>
94111

95112
/** The API of `LiteralArgument` instances.
96113
* The main source of information about annotations is the [[scala.reflect.api.Annotations]] page.
114+
* @group API
97115
*/
98116
trait LiteralArgumentApi {
99117
/** The underlying compile-time constant value. */
100118
def value: Constant
101119
}
102120

103121
/** An array argument to a Java annotation as in `@Target(value={TYPE,FIELD,METHOD,PARAMETER})`
122+
* @template
123+
* @group Annotations
104124
*/
105125
type ArrayArgument >: Null <: AnyRef with JavaArgument with ArrayArgumentApi
106126

107127
/** A tag that preserves the identity of the `ArrayArgument` abstract type from erasure.
108128
* Can be used for pattern matching, instance tests, serialization and likes.
129+
* @group Tags
109130
*/
110131
implicit val ArrayArgumentTag: ClassTag[ArrayArgument]
111132

112-
/** The constructor/deconstructor for `ArrayArgument` instances. */
133+
/** The constructor/deconstructor for `ArrayArgument` instances.
134+
* @group Extractors
135+
*/
113136
val ArrayArgument: ArrayArgumentExtractor
114137

115138
/** An extractor class to create and pattern match with syntax `ArrayArgument(args)`
116139
* where `args` is the argument array.
140+
* @group Extractors
117141
*/
118142
abstract class ArrayArgumentExtractor {
119143
def apply(args: Array[JavaArgument]): ArrayArgument
@@ -122,26 +146,33 @@ trait Annotations { self: Universe =>
122146

123147
/** API of `ArrayArgument` instances.
124148
* The main source of information about annotations is the [[scala.reflect.api.Annotations]] page.
149+
* @group API
125150
*/
126151
trait ArrayArgumentApi {
127152
/** The underlying array of Java annotation arguments. */
128153
def args: Array[JavaArgument]
129154
}
130155

131156
/** A nested annotation argument to a Java annotation as `@Nested` in `@Outer(@Nested)`.
157+
* @template
158+
* @group Annotations
132159
*/
133160
type NestedArgument >: Null <: AnyRef with JavaArgument with NestedArgumentApi
134161

135162
/** A tag that preserves the identity of the `NestedArgument` abstract type from erasure.
136163
* Can be used for pattern matching, instance tests, serialization and likes.
164+
* @group Tags
137165
*/
138166
implicit val NestedArgumentTag: ClassTag[NestedArgument]
139167

140-
/** The constructor/deconstructor for `NestedArgument` instances. */
168+
/** The constructor/deconstructor for `NestedArgument` instances.
169+
* @group Extractors
170+
*/
141171
val NestedArgument: NestedArgumentExtractor
142172

143173
/** An extractor class to create and pattern match with syntax `NestedArgument(annotation)`
144174
* where `annotation` is the nested annotation.
175+
* @group Extractors
145176
*/
146177
abstract class NestedArgumentExtractor {
147178
def apply(annotation: Annotation): NestedArgument
@@ -150,6 +181,7 @@ trait Annotations { self: Universe =>
150181

151182
/** API of `NestedArgument` instances.
152183
* The main source of information about annotations is the [[scala.reflect.api.Annotations]] page.
184+
* @group API
153185
*/
154186
trait NestedArgumentApi {
155187
/** The underlying nested annotation. */

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,18 @@ package api
33

44
/**
55
* This is an internal implementation class.
6+
* @groupname TreeBuilders Tree Building
67
*/
78
private[reflect] trait BuildUtils { self: Universe =>
89

10+
/** @group TreeBuilders */
911
val build: BuildApi
1012

1113
// this API abstracts away the functionality necessary for reification
1214
// it's too gimmicky and unstructured to be exposed directly in the universe
1315
// but we need it in a publicly available place for reification to work
1416

17+
/** @group TreeBuilders */
1518
abstract class BuildApi {
1619
/** Selects type symbol with given simple name `name` from the defined members of `owner`.
1720
*/

‎src/reflect/scala/reflect/api/Exprs.scala

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,17 +19,18 @@ import scala.reflect.runtime.{universe => ru}
1919
*
2020
* `Expr`s can also be created manually via the `Expr` companion object, but then the burden of providing a `TreeCreator` lies on the programmer.
2121
* Compile-time reflection via macros, as described in [[scala.reflect.macros.Aliases]], provides an easier way to instantiate exprs manually.
22-
* Manual creation, however, is very rarely needed when working with runtime reflection.
22+
* Manual creation, however, is very rarely needed when working with runtime reflection.
2323
*
2424
* `Expr` can be migrated from one mirror to another by using the `in` method. Migration means that all symbolic references
2525
* to classes/objects/packages in the expression are re-resolved within the new mirror
2626
* (typically using that mirror's classloader). The default universe of an `Expr` is typically
27-
* [[scala.reflect.runtime.package#universe]], the default mirror is typically [[scala.reflect.runtime.package#currentMirror]].
27+
* [[scala.reflect.runtime#universe]], the default mirror is typically [[scala.reflect.runtime#currentMirror]].
2828
*/
2929
trait Exprs { self: Universe =>
3030

3131
/** Expr wraps an abstract syntax tree and tags it with its type.
3232
* The main source of information about exprs is the [[scala.reflect.api.Exprs]] page.
33+
* @group Expressions
3334
*/
3435
trait Expr[+T] extends Equals with Serializable {
3536
/**
@@ -123,6 +124,7 @@ trait Exprs { self: Universe =>
123124
* in which case the tree first needs to be wrapped in an expr.
124125
125126
* The main source of information about exprs is the [[scala.reflect.api.Exprs]] page.
127+
* @group Expressions
126128
*/
127129
object Expr {
128130
def apply[T: WeakTypeTag](mirror: scala.reflect.api.Mirror[self.type], treec: TreeCreator): Expr[T] = new ExprImpl[T](mirror.asInstanceOf[Mirror], treec)

‎src/reflect/scala/reflect/api/FlagSets.scala

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,26 +32,35 @@ import scala.language.implicitConversions
3232
*/
3333
trait FlagSets { self: Universe =>
3434

35-
/** An abstract type representing sets of flags (like private, final, etc.) that apply to definition trees and symbols */
35+
/** An abstract type representing sets of flags (like private, final, etc.) that apply to definition trees and symbols
36+
* @template
37+
* @group Flags
38+
*/
3639
type FlagSet
3740

3841
/** A tag that preserves the identity of the `FlagSet` abstract type from erasure.
3942
* Can be used for pattern matching, instance tests, serialization and likes.
43+
* @group Tags
4044
*/
4145
implicit val FlagSetTag: ClassTag[FlagSet]
4246

4347
/** The API of `FlagSet` instances.
4448
* The main source of information about flag sets is the [[scala.reflect.api.FlagSets]] page.
49+
* @group Flags
4550
*/
4651
trait FlagOps extends Any {
4752
/** Produces a flag set that's a union of this flag set and the provided flag set. */
4853
def | (right: FlagSet): FlagSet
4954
}
5055

51-
/** The API of `FlagSet` instances. */
56+
/** The API of `FlagSet` instances.
57+
* @group Flags
58+
*/
5259
implicit def addFlagOps(left: FlagSet): FlagOps
5360

54-
/** A module that contains all possible values that can constitute flag sets. */
61+
/** A module that contains all possible values that can constitute flag sets.
62+
* @group Flags
63+
*/
5564
val Flag: FlagValues
5665

5766
// Q: I have a pretty flag. Can I put it here?
@@ -61,6 +70,7 @@ trait FlagSets { self: Universe =>
6170

6271
/** All possible values that can constitute flag sets.
6372
* The main source of information about flag sets is the [[scala.reflect.api.FlagSets]] page.
73+
* @group Flags
6474
*/
6575
trait FlagValues {
6676

@@ -140,6 +150,8 @@ trait FlagSets { self: Universe =>
140150
val DEFAULTINIT: FlagSet
141151
}
142152

143-
/** The empty set of flags */
153+
/** The empty set of flags
154+
* @group Flags
155+
*/
144156
val NoFlags: FlagSet
145157
}

‎src/reflect/scala/reflect/api/Importers.scala

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
package scala.reflect
22
package api
33

4-
/** This trait provides support for importers, a facility to migrate reflection artifacts between universes.
4+
/** This trait provides support for importers, a facility to migrate reflection artifacts between universes.
55
*
6-
* Reflection artifacts, such as symbols and types, are contained in universes. Typically all processing happens
7-
* within a single universe (e.g. a compile-time macro universe or a runtime reflection universe), but sometimes
8-
* there is a need to migrate artifacts from one universe to another. For example, runtime compilation works by
9-
* importing runtime reflection trees into a runtime compiler universe, compiling the importees and exporting the
6+
* Reflection artifacts, such as symbols and types, are contained in universes. Typically all processing happens
7+
* within a single universe (e.g. a compile-time macro universe or a runtime reflection universe), but sometimes
8+
* there is a need to migrate artifacts from one universe to another. For example, runtime compilation works by
9+
* importing runtime reflection trees into a runtime compiler universe, compiling the importees and exporting the
1010
* result back.
1111
*
12-
* Reflection artifacts are firmly grounded in their universes, which is reflected by the fact that types of artifacts
13-
* from different universes are not compatible. By using importers, however, they be imported from one universe
12+
* Reflection artifacts are firmly grounded in their universes, which is reflected by the fact that types of artifacts
13+
* from different universes are not compatible. By using importers, however, they be imported from one universe
1414
* into another. For example, to import `foo.bar.Baz` from the source universe to the target universe,
1515
* an importer will first check whether the entire owner chain exists in the target universe.
1616
* If it does, then nothing else will be done. Otherwise, the importer will recreate the entire owner chain
@@ -65,11 +65,14 @@ package api
6565
*/
6666
trait Importers { self: Universe =>
6767

68-
/** Creates an importer that moves reflection artifacts between universes. */
68+
/** Creates an importer that moves reflection artifacts between universes.
69+
* @group Importers
70+
*/
6971
def mkImporter(from0: Universe): Importer { val from: from0.type }
7072

7173
/** The API of importers.
7274
* The main source of information about importers is the [[scala.reflect.api.Importers]] page.
75+
* @group Importers
7376
*/
7477
trait Importer {
7578
/** The source universe of reflection artifacts that will be processed.

‎src/reflect/scala/reflect/api/JavaMirrors.scala

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,18 @@ package api
66
* This refinement equips mirrors with reflection capabilities for the JVM. `JavaMirror` can
77
* convert Scala reflection artifacts (symbols and types) into Java reflection artifacts (classes)
88
* and vice versa. It can also perform reflective invocations (getting/settings field values, calling methods, etc).
9+
* @groupname JavaMirrors Java Mirrors
910
*/
1011
trait JavaMirrors { self: JavaUniverse =>
1112

12-
/** In runtime reflection universes, runtime representation of a class is [[java.lang.Class]]. */
13+
/** In runtime reflection universes, runtime representation of a class is `java.lang.Class`.
14+
* @group JavaMirrors
15+
*/
1316
type RuntimeClass = java.lang.Class[_]
1417

15-
/** In runtime reflection universes, mirrors are JavaMirrors. */
18+
/** In runtime reflection universes, mirrors are JavaMirrors.
19+
* @group JavaMirrors
20+
*/
1621
override type Mirror >: Null <: JavaMirror
1722

1823
/** A refinement of [[scala.reflect.api.Mirror]] for runtime reflection using JVM classloaders.
@@ -22,6 +27,7 @@ trait JavaMirrors { self: JavaUniverse =>
2227
* become capable of performing reflective invocations (getting/settings field values, calling methods, etc).
2328
*
2429
* See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection.
30+
* @group JavaMirrors
2531
*/
2632
trait JavaMirror extends scala.reflect.api.Mirror[self.type] with RuntimeMirror {
2733
val classLoader: ClassLoader
@@ -30,6 +36,7 @@ trait JavaMirrors { self: JavaUniverse =>
3036

3137
/** Creates a runtime reflection mirror from a JVM classloader.
3238
* See [[scala.reflect.api.package the overview page]] for details on how to use runtime reflection.
39+
* @group JavaMirrors
3340
*/
3441
def runtimeMirror(cl: ClassLoader): Mirror
3542
}

‎src/reflect/scala/reflect/api/JavaUniverse.scala

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,20 @@ package api
66
* The refinement consists of an upgrade to the mirror API, which gets extended from [[scala.reflect.api.Mirror]]
77
* to [[scala.reflect.api.JavaMirrors#JavaMirror]].
88
*
9-
* See the [[docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for details on how to use runtime reflection.
9+
* See the [[http://docs.scala-lang.org/overviews/reflection/overview.html Reflection Guide]] for details on how to use runtime reflection.
10+
* @groupname JavaUniverse Java Mirrors
1011
*/
1112
trait JavaUniverse extends Universe with JavaMirrors { self =>
1213

14+
/* @group JavaUniverse */
1315
override def typeTagToManifest[T: ClassTag](mirror0: Any, tag: Universe # TypeTag[T]): Manifest[T] = {
1416
// SI-6239: make this conversion more precise
1517
val mirror = mirror0.asInstanceOf[Mirror]
1618
val runtimeClass = mirror.runtimeClass(tag.in(mirror).tpe)
1719
Manifest.classType(runtimeClass).asInstanceOf[Manifest[T]]
1820
}
1921

22+
/* @group JavaUniverse */
2023
override def manifestToTypeTag[T](mirror0: Any, manifest: Manifest[T]): Universe # TypeTag[T] =
2124
TypeTag(mirror0.asInstanceOf[Mirror], new TypeCreator {
2225
def apply[U <: Universe with Singleton](mirror: scala.reflect.api.Mirror[U]): U # Type = {

0 commit comments

Comments
 (0)