language tour: overhaul multiple parameter lists section (#1288)

Author: SethTisue

_tour/multiple-parameter-lists.md

@@ -13,15 +13,17 @@ previous-page: nested-functions
 redirect_from: "/tutorials/tour/multiple-parameter-lists.html"
 ---
 
-Methods may define multiple parameter lists. When a method is called with a fewer number of parameter lists, then this will yield a function taking the missing parameter lists as its arguments. This is formally known as [partial application](https://en.wikipedia.org/wiki/Partial_application).
+Methods may have multiple parameter lists.
 
-Here is an example, defined in [Traversable](/overviews/collections/trait-traversable.html) trait from Scala collections:
+### Example
+
+Here is an example, as defined on the `TraversableOnce` trait in Scala's collections API:
 
 ```
 def foldLeft[B](z: B)(op: (B, A) => B): B
 ```
 
-`foldLeft` applies a binary operator `op` to an initial value `z` and all elements of this traversable, going left to right. Shown below is an example of its usage. 
+`foldLeft` applies a two-parameter function `op` to an initial value `z` and all elements of this collection, going left to right. Shown below is an example of its usage.
 
 Starting with an initial value of 0, `foldLeft` here applies the function `(m, n) => m + n` to each element in the List and the previous accumulated value.
 
@@ -33,51 +35,49 @@ println(res) // 55
 ```
 {% endscalafiddle %}
 
-Multiple parameter lists have a more verbose invocation syntax; and hence should be used sparingly. Suggested use cases include:
+### Use cases
+
+Suggested use cases for multiple parameter lists include:
 
 #### Single functional parameter
-   In case of a single functional parameter, like `op` in the case of `foldLeft` above, multiple parameter lists allow a concise syntax to pass an anonymous function to the method. Without multiple parameter lists, the code would look like this:
+
+In case of a single functional parameter, like `op` in the case of `foldLeft` above, multiple parameter lists allow a concise syntax to pass an anonymous function to the method. Without multiple parameter lists, the code would look like this:
 
 ```
-numbers.foldLeft(0, {(m: Int, n: Int) => m + n})
+numbers.foldLeft(0, (m: Int, n: Int) => m + n)
 ```
-    
-   Note that the use of multiple parameter lists here also allows us to take advantage of Scala type inference to make the code more concise as shown below; which would not be possible in a non-curried definition.
-    
+
+Note that the use of multiple parameter lists here also allows us to take advantage of Scala type inference to make the code more concise, like this:
+
 ```
 numbers.foldLeft(0)(_ + _)
 ```
-   Also it allows us to fix the parameter `z` and pass around a partial function and reuse it as shown below:
-```tut
-val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
-val numberFunc = numbers.foldLeft(List[Int]())_
 
-val squares = numberFunc((xs, x) => xs:+ x*x)
-print(squares.toString()) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100)
+this would not be possible with only a single parameter list, as the Scala compiler would not be able to infer the parameter types of the function.
+
+#### Implicit parameters
+
+To specify only certain parameters as `implicit`, they must be placed in their own `implicit` parameter list.
+
+An example of this is:
 
-val cubes = numberFunc((xs, x) => xs:+ x*x*x)
-print(cubes.toString())  // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000)
+```
+def execute(arg: Int)(implicit ec: scala.concurrent.ExecutionContext) = ???
 ```
 
-   Finally, `foldLeft` and `foldRight` can be used in any of the following terms,
-```tut
-val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+#### Partial application
 
-numbers.foldLeft(0)((sum, item) => sum + item) // Generic Form
-numbers.foldRight(0)((sum, item) => sum + item) // Generic Form
+When a method is called with a fewer number of parameter lists, then this will yield a function taking the missing parameter lists as its arguments. This is formally known as [partial application](https://en.wikipedia.org/wiki/Partial_application).
 
-numbers.foldLeft(0)(_+_) // Curried Form
-numbers.foldRight(0)(_+_) // Curried Form
+For example,
 
-(0 /: numbers)(_+_) // Used in place of foldLeft
-(numbers :\ 0)(_+_) // Used in place of foldRight
-```   
+```tut
+val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+val numberFunc = numbers.foldLeft(List[Int]()) _
 
-   
-#### Implicit parameters
-   To specify certain parameters in a parameter list as `implicit`, multiple parameter lists should be used. An example of this is:
+val squares = numberFunc((xs, x) => xs :+ x*x)
+print(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100)
 
+val cubes = numberFunc((xs, x) => xs :+ x*x*x)
+print(cubes)  // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000)
 ```
-def execute(arg: Int)(implicit ec: ExecutionContext) = ???
-```
-