[Documentation] Trying to rewrite typeclasses-new #8147

aesteve · 2020-01-30T18:02:25Z

When first looking at this part of the doc, it wasn't completely clear to me.

For example:

Given instances, extension methods and context bounds allow a concise and natural expression of typeclasses.

I didn't really understand if extension methods and context bounds are needed to define a type class or if they simply help using them.

Typeclasses are just traits with canonical implementations defined by given instances

Simply using "whose" here helped me a bit. "Typeclasses are traits" (ok, so they're some abstract definition, fine), "whose implementation is" (oh ok, so this is the way of implementing the trait that differs, fine).

And finally, since the object Monoid with its apply method confused me a bit (is this part of a typeclass declaration?) I chose to first define the typeclass and use it without the object using summon, then add the object and remove summon.

Note that this is a "parti-pris" to rewrite the doc in a more "progressive" (or "tutorial") manner. And this may not be desirable feel free to tell me. That's not because I find it easier to understand this way, that everyone will...

Thanks for your reviews.

dottybot

Hello, and thank you for opening this PR! 🎉

All contributors have signed the CLA, thank you! ❤️

Have an awesome day! ☀️

docs/docs/reference/contextual/typeclasses-new.md

bishabosha · 2020-01-30T19:38:51Z

docs/docs/reference/contextual/typeclasses-new.md

+```scala
+assert(3 == List(1, 2).combineAll)
+```
+


Thanks for doing this, it's a lot more with the style of the rest of the documentation. If you apply the same style to the Functors and Monads section this will be really nice.

OK I'm not sure I have enough knowledge to re-write the Functor/Monad part in the same fashion (you need to understand properly to explain properly) but I will definitely give it a try.
If I'm struggling I'll ping you, so that you know you can merge this as is (best if the ennemy of good ;) ). But that's worth trying.

aesteve · 2020-01-31T10:01:55Z

I added parts re. functors and monad but left apart the Reader Monad.
I think I understand what it does and what it's useful for, but it's still hard to find the appropriate words to explain in trivial terms as in the other examples.

docs/docs/reference/contextual/typeclasses-new.md

bishabosha

Thank you for taking the time to write this tutorial. I think it will help people a lot. I've just made a few suggestions concerning correct use of definitions.

docs/docs/reference/contextual/typeclasses-new.md

Co-Authored-By: Jamie Thompson <[email protected]>

…hism Co-Authored-By: Jamie Thompson <[email protected]>

Co-Authored-By: Jamie Thompson <[email protected]>

…asses-new # Conflicts: # docs/docs/reference/contextual/typeclasses-new.md

… doc/rework-typeclasses-new

aesteve · 2020-02-09T12:57:56Z

Ready for review / merge.

bishabosha

you will need to change the filename to drop the -new now

aesteve · 2020-02-13T11:25:00Z

I have read that maybe we'll go back to given as so maybe I should still wait for a bit?

aesteve · 2020-02-27T10:48:24Z

I renamed given ... : to given ... as

bishabosha · 2020-02-27T12:56:49Z

docs/docs/reference/contextual/typeclasses.md

+
+The definition of a _typeclass_ is expressed via a parameterised type with abstract members, such as a `trait`.
+The main difference between object oriented polymorphism, and ad-hoc polymorphism with _typeclasses_, is how the definition of the _typeclass_ is implemented, in relation to the type it acts upon.
+In the case of a _typeclass_, its implementation for a concrete type is expressed through a `given` term definition, which is supplied as an implicit argument alongside the value it acts upon. With object oriented polymorphism, the implementation is mixed into the parents of a class, and only a single term is required to perform a polymorphic operation.


I think this part about comparing to OOP could be moved to the start

bishabosha · 2020-03-23T15:35:43Z

@aesteve What do you think about moving the comparison with OOP polymorphism?

aesteve · 2020-03-24T08:14:47Z

Hello.

Mixed feelings about this.

We could move the OO comparison at start (and remove the part about "it's just traits" or move it at the end) indeed.
In fact it depends which kind of reader we're trying to target.

For people who just want "I know, I know, just show me the syntax" a big intro with OOP comparison sounds quite "heavy", for people who don't know anything about typeclasses AND are familiar with OOP, it's accurate to have it at the start.

Honestly, that's quite a big "I don't know" for my part.

Do you want me to move it? Or should I give you access to my fork so that you can change it, or ?

bishabosha · 2020-03-24T09:38:49Z

For people who just want "I know, I know, just show me the syntax" a big intro with OOP comparison sounds quite "heavy", for people who don't know anything about typeclasses AND are familiar with OOP, it's accurate to have it at the start.

Honestly, that's quite a big "I don't know" for my part.

Maybe there can be an "aside" or some sort of box that can be skipped, my main concern was just that putting it at the very end seemed maybe out of place

bishabosha · 2020-03-29T20:28:17Z

I think in balance we would like to get this through, so If the wildcard type arguments are updated to use ? then this can be merged, thank you again for taking this on :)

aesteve · 2020-03-30T13:53:24Z

Oh sorry, I've missed some changes to upstream. Can you point me at the change, please?

bishabosha · 2020-03-30T14:32:33Z

Sure ok, have a look at http://dotty.epfl.ch/docs/reference/changed-features/wildcards.html

aesteve · 2020-03-30T16:20:00Z

Waw, didn't know about that :)

Should be ok now!

Re. the aside block, I may find a better organization in the future, but have unfortunately no time to look at it right now. Hopefully it's good enough as is, and can be reworked later on!

Thanks.

bishabosha · 2020-03-30T16:35:45Z

Great, thank you :)

bishabosha · 2020-04-29T15:01:31Z

This is now published

trying to rewrite typeclasses-new

a5c8aef

dottybot reviewed Jan 30, 2020

View reviewed changes

aesteve changed the title ~~Trying to rewrite typeclasses-new~~ [Documentation] Trying to rewrite typeclasses-new Jan 30, 2020

odersky reviewed Jan 30, 2020

View reviewed changes

docs/docs/reference/contextual/typeclasses-new.md Outdated Show resolved Hide resolved

bishabosha requested changes Jan 30, 2020

View reviewed changes

Wrap the last sentence in a whole "summary" section to avoid stray text

1bd517e

aesteve changed the title ~~[Documentation] Trying to rewrite typeclasses-new~~ [WIP] [Documentation] Trying to rewrite typeclasses-new Jan 31, 2020

Step2: rewrite the Functor part in more details

171a09a

aesteve requested a review from bishabosha January 31, 2020 10:00

Step3: rewrite the Monad part (apart from the Reader monad)

6b7e497

Arnaud ESTEVE added 3 commits January 31, 2020 11:05

Fix typos

74ff540

Rephrase assertTransformation simplification

8118ed7

Fix typos on the reader monad

a076eea

bishabosha reviewed Jan 31, 2020

View reviewed changes

docs/docs/reference/contextual/typeclasses-new.md Outdated Show resolved Hide resolved

@bishabosha's note

66ebcfb

aesteve requested a review from odersky January 31, 2020 10:34

attempt at explaining the reader monad

334c4b4

bishabosha requested changes Jan 31, 2020

View reviewed changes

bishabosha assigned aesteve Jan 31, 2020

aesteve and others added 10 commits January 31, 2020 15:11

less concrete and more accurate definition of a Functor

cd501b6

Co-Authored-By: Jamie Thompson <[email protected]>

definition of A functor, not THE functor ability

ff7ca15

Co-Authored-By: Jamie Thompson <[email protected]>

A functor for the type constructor F[_]

cf29e82

Co-Authored-By: Jamie Thompson <[email protected]>

better phrasing for abstracting away Config

8607014

Co-Authored-By: Jamie Thompson <[email protected]>

parameterised type with abstract members => trait

4c81c46

Co-Authored-By: Jamie Thompson <[email protected]>

oo polymorphism vs. parametric polymorphism

6b6cd39

Co-Authored-By: Jamie Thompson <[email protected]>

explaining the difference between OO polymorphism and ad-hoc polymorp…

c6ec581

…hism Co-Authored-By: Jamie Thompson <[email protected]>

better phrasing for conclusion

716ae0c

Co-Authored-By: Jamie Thompson <[email protected]>

remove the "we don't care" part

c15cd63

Co-Authored-By: Jamie Thompson <[email protected]>

using F as a substitution for every type that ca be mapped over

8b85b34

Co-Authored-By: Jamie Thompson <[email protected]>

Arnaud ESTEVE added 2 commits February 9, 2020 13:35

Merge remote-tracking branch 'upstream/master' into doc/rework-typecl…

86615f6

…asses-new # Conflicts: # docs/docs/reference/contextual/typeclasses-new.md

Merge remote-tracking branch 'origin/doc/rework-typeclasses-new' into…

f2d7a6d

… doc/rework-typeclasses-new

aesteve changed the title ~~[WIP] [Documentation] Trying to rewrite typeclasses-new~~ [Documentation] Trying to rewrite typeclasses-new Feb 9, 2020

Arnaud ESTEVE added 5 commits February 9, 2020 13:58

Trying to add an easy-to-grasp definition of type classes

df15a24

Proper 0.23 syntax

4b04603

Proper 0.23 syntax

cb6c511

typo

cd9834e

no longer given as

bf7b005

bishabosha requested changes Feb 13, 2020

View reviewed changes

typeclasses-new.md is now typeclasses.md

9c1509b

aesteve requested a review from bishabosha February 26, 2020 07:33

Adapt to 0.23 latest

466bff9

bishabosha reviewed Feb 27, 2020

View reviewed changes

bishabosha approved these changes Feb 27, 2020

View reviewed changes

bishabosha assigned bishabosha and unassigned aesteve Mar 23, 2020

Use new type wildcard syntax

219bc3c

bishabosha merged commit 3eafc18 into scala:master Mar 30, 2020

[Documentation] Trying to rewrite typeclasses-new #8147

[Documentation] Trying to rewrite typeclasses-new #8147

Uh oh!

Conversation

aesteve commented Jan 30, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dottybot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bishabosha Jan 30, 2020

Choose a reason for hiding this comment

Uh oh!

aesteve Jan 31, 2020

Choose a reason for hiding this comment

Uh oh!

aesteve commented Jan 31, 2020

Uh oh!

Uh oh!

bishabosha left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aesteve commented Feb 9, 2020

Uh oh!

bishabosha left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aesteve commented Feb 13, 2020

Uh oh!

aesteve commented Feb 27, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bishabosha Feb 27, 2020

Choose a reason for hiding this comment

Uh oh!

bishabosha commented Mar 23, 2020

Uh oh!

aesteve commented Mar 24, 2020

Uh oh!

bishabosha commented Mar 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bishabosha commented Mar 29, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aesteve commented Mar 30, 2020

Uh oh!

bishabosha commented Mar 30, 2020

Uh oh!

aesteve commented Mar 30, 2020

Uh oh!

bishabosha commented Mar 30, 2020

Uh oh!

bishabosha commented Apr 29, 2020

Uh oh!

Uh oh!

aesteve commented Jan 30, 2020 •

edited

Loading

bishabosha left a comment •

edited

Loading

bishabosha left a comment •

edited

Loading

aesteve commented Feb 27, 2020 •

edited

Loading

bishabosha commented Mar 24, 2020 •

edited

Loading

bishabosha commented Mar 29, 2020 •

edited

Loading