Try to clarify implicit parameters tour #1018
Conversation
* Don't explain what a monoid and a semigroup are. This is not the place for that. * Don't make `Monoid[A]` extend `Semigroup[A]`. This only complicates the example for no gain. * Explain the lookup procedure. * Use "Companion object" instead of "companion module" * Don't mention templates. It's an uncommonly used * Don't extend `App`. It doesn't simplify the example. Further improvements could be to show an example of the second rule of implicit lookup, and/or a chained implicit lookup.
_tour/implicit-parameters.md
Outdated
|
|
||
| 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: |
There was a problem hiding this comment.
nit: capitalize "Scala" consistently
_tour/implicit-parameters.md
Outdated
| * 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. | ||
| * First, eligible are all identifiers 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 objects of the implicit parameter's type that are labeled implicit. |
There was a problem hiding this comment.
I know it was like this, but the phrasing "eligible are all identifiers that ..." sounds like a 19th century legal text.
Why not something like...
... two categories:
- Implicit definitions and implicit parameters that can be referenced at the point of the method call without a prefix, and
- Members of companion objects of the implicit parameter's type that are marked implicit.
This elides the "parts" bit from the spec but I think that is needlessly complicated to mention in the tour.
There was a problem hiding this comment.
The swing I took at this also addresses the two below comments. WDYT?
_tour/implicit-parameters.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
consistent capitalization opportunity
_tour/implicit-parameters.md
Outdated
|
|
||
| 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 identifier, it can be accessed directly in `main`, and it is an implicit definition. It is also of the correct type, so it's passed to the sum method automatically. |
There was a problem hiding this comment.
Maybe,
Because
IntMonoidis a value which can be referenced directly inside ofmain, is marked implicit, and has the correct type, it's passed automatically tosum.
Otherwise, "sum" should probably be "sum".
_tour/implicit-parameters.md
Outdated
| def unit: A | ||
| } | ||
| object ImplicitTest extends App { | ||
|
|
||
| object ImplicitTest { | ||
| implicit object StringMonoid extends Monoid[String] { |
There was a problem hiding this comment.
There are some gotchas with implicit objects last time I checked, and the type of StringMonoid isn't really Monoid[String]. I think this should be implicit val StringMonoid: Monoid[String] = ....
Make it read less like Ye Olde Specificatione of Ye Scaelae Language
_tour/implicit-parameters.md
Outdated
| * 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 falls back to all members that are marked implicit in the companion object of the implicit parameter. |
There was a problem hiding this comment.
What about "Then it looks for members marked implicit in all the companion objects associated with the implicit candidate type"? A link to https://docs.scala-lang.org/tutorials/FAQ/finding-implicits.html would be useful for those that want to know more.
There was a problem hiding this comment.
Linking to the implicit lookup FAQ there is a great idea.
The phrasing "in all the companion objects associated with the implicit candidate type" isn't as "human readable" as I'd like it to be, especially for the tour. It still reads a bit as legalese. I'll think on it some more. Maybe not saying much about where it looks exactly (but link to the FAQ for details) is another option.
|
Won't it interfere with: As part of this work, I would remove older files related to implicits, and there would be a single implicit.md. |
|
thanks Martijn & reviewers, nice work here. |
Monoid[A]extendSemigroup[A]. This only complicates the example for no gain.App. It doesn't simplify the example.Further improvements could be to show an example of the second rule of implicit lookup, and/or a chained implicit lookup.