Tweak implicit classes overview

Author: som-snytt

_overviews/core/implicit-classes.md

@@ -13,47 +13,71 @@ permalink: /overviews/core/:title.html
 
 ## Introduction
 
-Scala 2.10 introduced a new feature called *implicit classes*.  An *implicit class* is a class
-marked with the `implicit` keyword.  This keyword makes the class's primary constructor available
-for implicit conversions when the class is in scope.
+Scala 2.10 introduced a new feature called *implicit classes*. An *implicit class* is a class
+marked with the `implicit` keyword. The `implicit` keyword makes the class's primary constructor available
+for implicit conversions when the class is in scope. This mechanism is used to add "extension methods"
+to the type of the class parameter.
 
-Implicit classes were proposed in [SIP-13](https://docs.scala-lang.org/sips/pending/implicit-classes.html).
+Implicit classes were proposed in [SIP-13](https://docs.scala-lang.org/sips/implicit-classes.html).
 
 ## Usage
 
 To create an implicit class, simply place the `implicit` keyword in front of an appropriate
-class.  Here's an example:
+class:
 
     object Helpers {
-      implicit class IntWithTimes(x: Int) {
-        def times[A](f: => A): Unit = {
+      implicit class `keep up with the times`(n: Int) {
+        def times[A](body: => A): Unit = {
           def loop(current: Int): Unit =
-            if(current > 0) {
-              f
+            if (current > 0) {
+              body
               loop(current - 1)
             }
-          loop(x)
+          loop(n)
         }
       }
     }
 
-This example creates the implicit class `IntWithTimes`.  This class wraps an `Int` value and provides
-a new method, `times`.   To use this class, just import it into scope and call the `times` method.
-Here's an example:
+This example creates the implicit class `keep up with the times`.
+The purpose of the funny name is to avoid name collisions.
+If it's desirable to avoid importing the implicit, then a conventional name
+such as `IntWithTimes` would enable an exclusionary import:
+
+    import Helpers.{IntWithTimes => _, _}
+
+This class wraps an `Int` value and provides a new method, `times`.
+To use this class, just import it into scope and call the `times` method:
 
     scala> import Helpers._
     import Helpers._
 
-    scala> 5 times println("HI")
-    HI
-    HI
-    HI
-    HI
-    HI
+    scala> 5 times println("hello, world")
+    hello, world
+    hello, world
+    hello, world
+    hello, world
+    hello, world
 
 For an implicit class to work, its name must be in scope and unambiguous, like any other implicit
-value or conversion.
+value or conversion. The important consideration is that the implicit class definition
+also introduces a method with the same name and parameters as the class. That method just
+forwards to the class constructor. A user-defined method with the same name and parameters would result
+in a compilation error.
+
+The usual rules for implicit resolution apply:
+
+    trait T
 
+    object T {
+      implicit class `t can f`(t: T) {
+        def f = 42
+      }
+    }
+
+    object Test extends App {
+      val t = null.asInstanceOf[T]
+      println(t.f)
+    }
 
 ## Restrictions
 
@@ -80,14 +104,16 @@ While it's possible to create an implicit class with more than one non-implicit
 aren't used during implicit lookup.
 
 
-**3. There may not be any method, member or object in scope with the same name as the implicit class.**
+**3. The `implicit def` introduced by `implicit class` must not be ambiguous with respect to other term members.**
 
-*Note: This means an implicit class cannot be a case class*.
+*Note: This means an implicit class cannot be a case class*. The reason for this restriction is shown below.
+In particular, `Baz(42)` is ambiguous because it means both the method `Baz` and the companion `Baz.apply(42)`.
+Therefore, `implicit case class` is outlawed outright.
 
     object Bar
-    implicit class Bar(x: Int) // BAD!
+    implicit class Bar(x: Int) // BAD! in local scope, there is no overloading
 
     val x = 5
-    implicit class x(y: Int) // BAD!
+    implicit class x(y: Int) // BAD! in local scope, there is no overloading
 
-    implicit case class Baz(x: Int) // BAD!
+    implicit case class Baz(x: Int) // BAD! the companion apply and implicit def are ambiguous together