@@ -92,8 +92,10 @@ object language {
92
92
*/
93
93
@ volatile implicit lazy val reflectiveCalls : reflectiveCalls = languageFeature.reflectiveCalls
94
94
95
- /** Only where enabled, definitions of implicit conversions are allowed. An
96
- * implicit conversion is an implicit value of unary function type `A => B`,
95
+ /** Only where enabled, definitions of legacy implicit conversions and certain uses
96
+ * of implicit conversions are allowed.
97
+ *
98
+ * A legacy implicit conversion is an implicit value of unary function type `A => B`,
97
99
* or an implicit method that has in its first parameter section a single,
98
100
* non-implicit parameter. Examples:
99
101
*
@@ -103,17 +105,36 @@ object language {
103
105
* implicit def listToX(xs: List[T])(implicit f: T => X): X = ...
104
106
* }}}
105
107
*
106
- * implicit values of other types are not affected, and neither are implicit
107
- * classes.
108
+ * Implicit values of other types are not affected, and neither are implicit
109
+ * classes. In particular, implied instances of the scala.Conversion class can be
110
+ * defined without having to import the language feature.
111
+ *
112
+ * The language import is also required to enable _uses_ of implicit conversions
113
+ * unless the conversion in question is co-defined with the type to which it maps.
114
+ * Co-defined means: defined in the companion object of the class of the result type.
115
+ * Examples:
116
+ *
117
+ * {{{
118
+ * class A
119
+ * class B
120
+ * object B {
121
+ * implied a2b for Conversion[A, B] { ... }
122
+ * }
123
+ * object C {
124
+ * implied b2a for Conversion[B, A] { ... }
125
+ * }
126
+ * import implied B._
127
+ * import implied C._
128
+ * val x: A = new B // language import required
129
+ * val x: B = new A // no import necessary since a2b is co-defined with B
130
+ * }}}
108
131
*
109
132
* '''Why keep the feature?''' Implicit conversions are central to many aspects
110
133
* of Scala’s core libraries.
111
134
*
112
135
* '''Why control it?''' Implicit conversions are known to cause many pitfalls
113
- * if over-used. And there is a tendency to over-use them because they look
114
- * very powerful and their effects seem to be easy to understand. Also, in
115
- * most situations using implicit parameters leads to a better design than
116
- * implicit conversions.
136
+ * if over-used. This holds in particular for implicit conversions defined after
137
+ * the fact between unrelated types.
117
138
*
118
139
* @group production
119
140
*/
0 commit comments