From 3eb01d3741fb00131f8ab2569a5b5d8a3a15fefc Mon Sep 17 00:00:00 2001 From: Nikolay Yakimov Date: Tue, 15 Aug 2017 13:22:33 +0300 Subject: [PATCH 1/2] tour/implicit-paramteres: format overlong code comments --- _tour/implicit-parameters.md | 40 +++++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/_tour/implicit-parameters.md b/_tour/implicit-parameters.md index d1868d8779..f707902c23 100644 --- a/_tour/implicit-parameters.md +++ b/_tour/implicit-parameters.md @@ -23,16 +23,28 @@ The actual arguments that are eligible to be passed to an implicit parameter fal 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. ```tut -/** This example uses a structure from abstract algebra to show how implicit parameters work. A semigroup is an algebraic structure on a set A with an (associative) operation, called add here, that combines a pair of A's and returns another A. */ +/** This example uses a structure from abstract algebra to show + how implicit parameters work. A semigroup is an algebraic + structure on a set A with an (associative) operation, called + add here, that combines a pair of A's and returns another A. + */ abstract class SemiGroup[A] { def add(x: A, y: A): A } -/** A monoid 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. */ +/** A monoid 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. + */ abstract class Monoid[A] extends SemiGroup[A] { def unit: A } object ImplicitTest extends App { - /** To show how implicit parameters work, we first define monoids for strings and integers. The implicit keyword indicates that the corresponding object can be used implicitly, within this scope, as a parameter of a function marked implicit. */ + /** To show how implicit parameters work, we first define + monoids for strings and integers. The implicit keyword + indicates that the corresponding object can be used + implicitly, within this scope, as a parameter of a + function marked implicit. + */ implicit object StringMonoid extends Monoid[String] { def add(x: String, y: String): String = x concat y def unit: String = "" @@ -41,14 +53,28 @@ object ImplicitTest extends App { def add(x: Int, y: Int): Int = x + y def unit: Int = 0 } - /** This method takes a List[A] returns an A which represent the combined value 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. */ + /** This method takes a List[A] returns an A which represent + the combined value 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. + */ def sum[A](xs: List[A])(implicit m: Monoid[A]): A = if (xs.isEmpty) m.unit else m.add(xs.head, sum(xs.tail)) - /** Here 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. */ - println(sum(List(1, 2, 3))) // uses IntMonoid implicitly - println(sum(List("a", "b", "c"))) // uses StringMonoid implicitly + /** Here 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. + */ + println(sum(List(1, 2, 3))) // uses IntMonoid implicitly + println(sum(List("a", "b", "c"))) // uses StringMonoid implicitly } ``` From ba3d2fe5d00440ce5c4554ee8392a48d4e5b97bc Mon Sep 17 00:00:00 2001 From: Nikolay Yakimov Date: Tue, 15 Aug 2017 13:41:23 +0300 Subject: [PATCH 2/2] tour/implicit-paramteres: move long comments into text --- _tour/implicit-parameters.md | 41 +++++++++--------------------------- 1 file changed, 10 insertions(+), 31 deletions(-) diff --git a/_tour/implicit-parameters.md b/_tour/implicit-parameters.md index f707902c23..0a3da1634a 100644 --- a/_tour/implicit-parameters.md +++ b/_tour/implicit-parameters.md @@ -23,28 +23,13 @@ The actual arguments that are eligible to be passed to an implicit parameter fal 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. ```tut -/** This example uses a structure from abstract algebra to show - how implicit parameters work. A semigroup is an algebraic - structure on a set A with an (associative) operation, called - add here, that combines a pair of A's and returns another A. - */ abstract class SemiGroup[A] { def add(x: A, y: A): A } -/** A monoid 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. - */ abstract class Monoid[A] extends SemiGroup[A] { def unit: A } object ImplicitTest extends App { - /** To show how implicit parameters work, we first define - monoids for strings and integers. The implicit keyword - indicates that the corresponding object can be used - implicitly, within this scope, as a parameter of a - function marked implicit. - */ implicit object StringMonoid extends Monoid[String] { def add(x: String, y: String): String = x concat y def unit: String = "" @@ -53,31 +38,25 @@ object ImplicitTest extends App { def add(x: Int, y: Int): Int = x + y def unit: Int = 0 } - /** This method takes a List[A] returns an A which represent - the combined value 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. - */ def sum[A](xs: List[A])(implicit m: Monoid[A]): A = if (xs.isEmpty) m.unit else m.add(xs.head, sum(xs.tail)) - /** Here 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. - */ 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`. + +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. + +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. + +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. + +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. + Here is the output of the Scala program: ```