@@ -22,11 +22,11 @@ package scala
22
22
*
23
23
* The language features are:
24
24
* - [[dynamics `dynamics` ]] enables defining calls rewriting using the [[scala.Dynamic `Dynamic` ]] trait
25
- * - [[postfixOps `postfixOps` ]] enables postfix operators
26
- * - [[reflectiveCalls `reflectiveCalls` ]] enables using structural types
27
- * - [[implicitConversions `implicitConversions` ]] enables defining implicit methods and members
28
- * - [[higherKinds `higherKinds` ]] enables writing higher-kinded types
29
25
* - [[existentials `existentials` ]] enables writing existential types
26
+ * - [[higherKinds `higherKinds` ]] enables writing higher-kinded types
27
+ * - [[implicitConversions `implicitConversions` ]] enables defining implicit methods and members
28
+ * - [[postfixOps `postfixOps` ]] enables postfix operators (not recommended)
29
+ * - [[reflectiveCalls `reflectiveCalls` ]] enables using structural types
30
30
* - [[experimental `experimental` ]] contains newer features that have not yet been tested in production
31
31
*
32
32
* @groupname production Language Features
@@ -37,10 +37,11 @@ object language {
37
37
38
38
import languageFeature ._
39
39
40
- /** Where enabled, direct or indirect subclasses of trait scala.Dynamic can
41
- * be defined. Unless dynamics is enabled, a definition of a class, trait,
42
- * or object that has Dynamic as a base trait is rejected. Dynamic member
43
- * selection of existing subclasses of trait Dynamic are unaffected;
40
+ /** Only where this feature is enabled, can direct or indirect subclasses of trait scala.Dynamic
41
+ * be defined. If `dynamics` is not enabled, a definition of a class, trait,
42
+ * or object that has `Dynamic` as a base trait is rejected by the compiler.
43
+ *
44
+ * Selections of dynamic members of existing subclasses of trait `Dynamic` are unaffected;
44
45
* they can be used anywhere.
45
46
*
46
47
* '''Why introduce the feature?''' To enable flexible DSLs and convenient interfacing
@@ -54,19 +55,28 @@ object language {
54
55
*/
55
56
implicit lazy val dynamics : dynamics = languageFeature.dynamics
56
57
57
- /** Only where enabled, postfix operator notation `(expr op)` will be allowed.
58
+ /** Only where this feature is enabled, is postfix operator notation `(expr op)` permitted.
59
+ * If `postfixOps` is not enabled, an expression using postfix notation is rejected by the compiler.
58
60
*
59
- * '''Why keep the feature?''' Several DSLs written in Scala need the notation.
61
+ * '''Why keep the feature?''' Postfix notation is preserved for backward
62
+ * compatibility only. Historically, several DSLs written in Scala need the notation.
60
63
*
61
64
* '''Why control it?''' Postfix operators interact poorly with semicolon inference.
62
- * Most programmers avoid them for this reason.
65
+ * Most programmers avoid them for this reason alone. Postfix syntax is
66
+ * associated with an abuse of infix notation, `a op1 b op2 c op3`,
67
+ * that can be harder to read than ordinary method invocation with judicious
68
+ * use of parentheses. It is recommended not to enable this feature except for
69
+ * legacy code.
63
70
*
64
71
* @group production
65
72
*/
66
73
implicit lazy val postfixOps : postfixOps = languageFeature.postfixOps
67
74
68
- /** Only where enabled, accesses to members of structural types that need
69
- * reflection are supported. Reminder: A structural type is a type of the form
75
+ /** Where this feature is enabled, accesses to members of structural types that need
76
+ * reflection are supported. If `reflectiveCalls` is not enabled, an expression
77
+ * requiring reflection will trigger a warning from the compiler.
78
+ *
79
+ * A structural type is a type of the form
70
80
* `Parents { Decls }` where `Decls` contains declarations of new members that do
71
81
* not override any member in `Parents`. To access one of these members, a
72
82
* reflective call is needed.
@@ -83,8 +93,11 @@ object language {
83
93
*/
84
94
implicit lazy val reflectiveCalls : reflectiveCalls = languageFeature.reflectiveCalls
85
95
86
- /** Only where enabled, definitions of implicit conversions are allowed. An
87
- * implicit conversion is an implicit value of unary function type `A => B`,
96
+ /** Where this feature is enabled, definitions of implicit conversions are allowed.
97
+ * If `implicitConversions` is not enabled, the definition of an implicit
98
+ * conversion will trigger a warning from the compiler.
99
+ *
100
+ * An implicit conversion is an implicit value of unary function type `A => B`,
88
101
* or an implicit method that has in its first parameter section a single,
89
102
* non-implicit parameter. Examples:
90
103
*
@@ -94,8 +107,8 @@ object language {
94
107
* implicit def listToX(xs: List[T])(implicit f: T => X): X = ...
95
108
* }}}
96
109
*
97
- * implicit values of other types are not affected, and neither are implicit
98
- * classes .
110
+ * Implicit classes and implicit values of other types are not governed by this
111
+ * language feature .
99
112
*
100
113
* '''Why keep the feature?''' Implicit conversions are central to many aspects
101
114
* of Scala’s core libraries.
@@ -110,7 +123,9 @@ object language {
110
123
*/
111
124
implicit lazy val implicitConversions : implicitConversions = languageFeature.implicitConversions
112
125
113
- /** Only where this flag is enabled, higher-kinded types can be written.
126
+ /** Where this feature is enabled, higher-kinded types can be written.
127
+ * If `higherKinds` is not enabled, a higher-kinded type such as `F[A]`
128
+ * will trigger a warning from the compiler.
114
129
*
115
130
* '''Why keep the feature?''' Higher-kinded types enable the definition of very general
116
131
* abstractions such as functor, monad, or arrow. A significant set of advanced
@@ -133,9 +148,12 @@ object language {
133
148
*/
134
149
implicit lazy val higherKinds : higherKinds = languageFeature.higherKinds
135
150
136
- /** Only where enabled, existential types that cannot be expressed as wildcard
151
+ /** Where this feature is enabled, existential types that cannot be expressed as wildcard
137
152
* types can be written and are allowed in inferred types of values or return
138
- * types of methods. Existential types with wildcard type syntax such as `List[_]`,
153
+ * types of methods. If `existentials` is not enabled, those cases will trigger
154
+ * a warning from the compiler.
155
+ *
156
+ * Existential types with wildcard type syntax such as `List[_]`,
139
157
* or `Map[String, _]` are not affected.
140
158
*
141
159
* '''Why keep the feature?''' Existential types are needed to make sense of Java’s wildcard
@@ -151,8 +169,8 @@ object language {
151
169
*/
152
170
implicit lazy val existentials : existentials = languageFeature.existentials
153
171
154
- /** The experimental object contains features that have been recently added but have not
155
- * been thoroughly tested in production yet .
172
+ /** The experimental object contains features that are known to have unstable API or
173
+ * behavior that may change in future releases .
156
174
*
157
175
* Experimental features '''may undergo API changes''' in future releases, so production
158
176
* code should not rely on them.
@@ -167,8 +185,11 @@ object language {
167
185
168
186
import languageFeature .experimental ._
169
187
170
- /** Where enabled, macro definitions are allowed. Macro implementations and
171
- * macro applications are unaffected; they can be used anywhere.
188
+ /** Only where this feature is enabled, are macro definitions allowed.
189
+ * If `macros` is not enabled, macro definitions are rejected by the compiler.
190
+ *
191
+ * Macro implementations and macro applications are not governed by this
192
+ * language feature; they can be used anywhere.
172
193
*
173
194
* '''Why introduce the feature?''' Macros promise to make the language more regular,
174
195
* replacing ad-hoc language constructs with a general powerful abstraction
0 commit comments