Add tut doc for FunctionK

[ceedubs]

I'm sure that there is more that could be done with this, and I'm very
open to recommendations, but I wanted to get something out there.

[codecov-io]

Codecov Report

Merging #1604 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1604   +/-   ##
=======================================
  Coverage   93.11%   93.11%           
=======================================
  Files         250      250           
  Lines        3992     3992           
  Branches      138      136    -2     
=======================================
  Hits         3717     3717           
  Misses        275      275

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4e381d2...3837a08. Read the comment docs.

[kailuowang]

I like the step by step concpets derivation.

[edmundnoble]

Very nice! I am still uncomfortable with this "operates on kinds" malarkey, especially after discussion in #1358, but that should probably be removed en-masse if at all.

[ceedubs]

@edmundnoble thanks for drawing attention to the "operates on kinds" wording. I agree that it's at best sloppy.

I'm trying to think of what a better alternate wording word be. The ScalaDoc for FunctionK says

FunctionK[F[_], G[_]] is a functor transformation from F to G
in the same manner that function A => B is a morphism from values
of type A to B.

While this is a more accurate description, I think that it's probably not going to be much help to many people who are looking at FunctionK for the first time. I'd prefer something a little more approachable since FunctionK is really a fairly simple concept.

What do you think about something like:

A FunctionK transforms values from one first-order-kinded type (a type that takes a single type parameter, such as List or Option) into another first-order-kinded type. This transformation is universal, meaning that a FunctionK[List, Option] will translate all List[A] values into an Option[A] value for all possible types of A.

This explanation may be easier to understand if we first step back and talk about ordinary functions.

[kailuowang]

A FunctionK transforms values from one first-order-kinded type (a type that takes a single type parameter, such as List or Option)

Will the language here gives people the impression that it won't work for " Either[L, ?]". How about "...such as List, Option or Either[L, ?] if partial unification is enabled"?

[ceedubs]

@kailuowang I suppose that's a possibility. But I also am hesitant to try to shove much more information into that intro description. Maybe it would be better to provide an example with a type such as Either[L, ?] further down in the document?

[ceedubs]

@edmundnoble @kailuowang @peterneyens I've made some changes:

• Clean up sloppy usage of the term "kind"
• Mention the ~> type alias
• Show example of fixing the left of Either to make it work with FunctionK.

When you get a chance, please take another look and let me know what you think.

[peterneyens]

We still need to add a menu link.

[ceedubs]

@peterneyens good catch. I've added the menu link.

[kailuowang]

LGTM 👍