Try to clarify implicit parameters tour

_tour/implicit-parameters.md

@@ -13,52 +13,60 @@ previous-page: self-types
 redirect_from: "/tutorials/tour/implicit-parameters.html"
 ---
 
-A method with _implicit parameters_ can be applied to arguments just like a normal method. In this case the implicit label has no effect. However, if such a method misses arguments for its implicit parameters, such arguments will be automatically provided.
+A method can have an _implicit_ parameter list, marked by the _implicit_ keyword at the start of the parameter list. If the parameters in that parameter list are not passed as usual, Scala will look if it can get an implicit value of the correct type, and if it can, pass it automatically.
 
-The actual arguments that are eligible to be passed to an implicit parameter fall into two categories:
+The places Scala will look for these parameters fall into two categories:
 
-* First, eligible are all identifiers x that can be accessed at the point of the method call without a prefix and that denote an implicit definition or an implicit parameter.
-* Second, eligible are also all members of companion modules of the implicit parameter's type that are labeled implicit.
+* Scala will first look for implicit definitions and implicit parameters that can be accessed directly (without a prefix) at the point the method with the implicit parameter block is called.
+* Then it looks for members marked implicit in all the companion objects associated with the implicit candidate type.
 
-In the following example we define a method `sum` which computes the sum of a list of elements using the monoid's `add` and `unit` operations. Please note that implicit values can not be top-level, they have to be members of a template.
+A more detailed guide to where scala looks for implicits can be found in [the FAQ](//docs.scala-lang.org/tutorials/FAQ/finding-implicits.html)
+
+In the following example we define a method `sum` which computes the sum of a list of elements using the monoid's `add` and `unit` operations. Please note that implicit values can not be top-level.
 
 ```tut
-abstract class SemiGroup[A] {
+abstract class Monoid[A] {
   def add(x: A, y: A): A
-}
-abstract class Monoid[A] extends SemiGroup[A] {
   def unit: A
 }
-object ImplicitTest extends App {
-  implicit object StringMonoid extends Monoid[String] {
+
+object ImplicitTest {
+  implicit val stringMonoid: Monoid[String] = new Monoid[String] {
     def add(x: String, y: String): String = x concat y
     def unit: String = ""
   }
-  implicit object IntMonoid extends Monoid[Int] {
+
+  implicit val intMonoid: Monoid[Int] = new Monoid[Int] {
     def add(x: Int, y: Int): Int = x + y
     def unit: Int = 0
   }
+
   def sum[A](xs: List[A])(implicit m: Monoid[A]): A =
     if (xs.isEmpty) m.unit
     else m.add(xs.head, sum(xs.tail))
-
-  println(sum(List(1, 2, 3)))       // uses IntMonoid implicitly
-  println(sum(List("a", "b", "c"))) // uses StringMonoid implicitly
+
+  def main(args: Array[String]): Unit = {
+    println(sum(List(1, 2, 3)))       // uses IntMonoid implicitly
+    println(sum(List("a", "b", "c"))) // uses StringMonoid implicitly
+  }
 }
 ```
 
-This example uses a structure from abstract algebra to show how implicit parameters work. A semigroup, modeled by `SemiGroup` here, is an algebraic structure on a set of `A` with an (associative) operation, called `add` here, that combines a pair of `A`s and returns another `A`.
+`Monoid` defines an operation called `add` here, that combines a pair of `A`s and returns another `A`, together with an operation called `unit` that is able to create some (specific) `A`.
+
+To show how implicit parameters work, we first define monoids `StringMonoid` and `IntMonoid` for strings and integers, respectively. The `implicit` keyword indicates that the corresponding object can be used implicitly.
 
-A monoid, modeled by `Monoid` here, is a semigroup with a distinguished element of `A`, called `unit`, that when combined with any other element of `A` returns that other element again.
+The method `sum` takes a `List[A]` and returns an `A`, which takes the initial `A` from `unit`, and combines each next `A` in the list to that with the `add` method. Making the parameter `m` implicit here means we only have to provide the `xs` parameter when we call the method if Scala can find a an implict `Monoid[A]` to use for the implicit `m` parameter.
 
-To show how implicit parameters work, we first define monoids `StringMonoid` and `IntMonoid` for strings and integers, respectively. The `implicit` keyword indicates that the corresponding object can be used implicitly, within this scope, as a parameter of a function marked implicit.
+In our `main` method we call `sum` twice, and only provide the `xs` parameter. Scala will now look for an implicit in the scope mentioned above. The first call to `sum` passes a `List[Int]` for `xs`, which means that `A` is `Int`. The implicit parameter list with `m` is left out, so Scala will look for an implicit of type `Monoid[Int]`. The first lookup rule reads
 
-Method `sum` takes a `List[A]` and returns an `A`, which represents the result of applying the monoid operation successively across the whole list. Making the parameter `m` implicit here means we only have to provide the `xs` parameter at the call site, since if we have a `List[A]` we know what type `A` actually is and therefore what type `Monoid[A]` is needed. We can then implicitly find whichever `val` or `object` in the current scope also has that type and use that without needing to specify it explicitly.
+> Scala will first look for implicit definitions and implicit parameters that can be accessed directly (without a prefix) at the point the method with the implicit parameter block is called.
 
-Finally, we call `sum` twice, with only one parameter each time. Since the second parameter of `sum`, `m`, is implicit, its value is looked up in the current scope, based on the type of monoid required in each case, meaning both expressions can be fully evaluated.
+`intMonoid` is an implicit definition that can be accessed directly directly in `main`. It is also of the correct type, so it's passed to the sum method automatically.
 
-Here is the output of the Scala program:
+The second call to `sum` passes a `List[String]`, which means that `A` is `String`. Implicit lookup will go the same way as with `Int`, but will this time find `stringMonoid`, and passes that automatically as `m`.
 
+The program will output
 ```
 6
 abc