@@ -92,8 +92,10 @@ object language {
9292 */
9393 @ volatile implicit lazy val reflectiveCalls : reflectiveCalls = languageFeature.reflectiveCalls
9494
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`,
9799 * or an implicit method that has in its first parameter section a single,
98100 * non-implicit parameter. Examples:
99101 *
@@ -103,17 +105,36 @@ object language {
103105 * implicit def listToX(xs: List[T])(implicit f: T => X): X = ...
104106 * }}}
105107 *
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+ * }}}
108131 *
109132 * '''Why keep the feature?''' Implicit conversions are central to many aspects
110133 * of Scala’s core libraries.
111134 *
112135 * '''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.
117138 *
118139 * @group production
119140 */
0 commit comments