Add docs for Ior

[LukaJCB]

Some basic usage so far. Might make sense to also document more of the methods available on Ior:)

[codecov-io]

Codecov Report

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

@@           Coverage Diff           @@
##           master    #1822   +/-   ##
=======================================
  Coverage   95.54%   95.54%           
=======================================
  Files         248      248           
  Lines        4420     4420           
  Branches      121      124    +3     
=======================================
  Hits         4223     4223           
  Misses        197      197

---

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 7c74048...01aa2f0. Read the comment docs.

[kailuowang]

noice, thanks!

[ceedubs]

Thanks @LukaJCB. Good stuff!

I left one small comment about an Xor reference that I think it might be a good idea for us to change.

My favorite example of Ior is using List[A Ior B] as a return type for a method that zips two lists together, but I suppose it would be out of place to shove that example into this doc :)

[ceedubs]

I'm a bit hesitant about this Xor reference. I think that this might be confusing, as Cats no longer has an Xor type. For consistency with the previous sentence, it might be better to write this as "which represents an exclusive-or" relationship.

In logic/circuits, this is often written as XOR, which we could potentially use, but I think that exclusive-or is more straightforward.

[peterneyens]

Without the Ior syntax, you could do Ior.leftNel("Can't be empty").

[peterneyens]

If you are creating a one element NonEmptyList you can use NonEmptyList.one instead of NonEmptyList.of.

[peterneyens]

Not sure if we want to introduce that here, but there also is a IorNel type alias.

[peterneyens]

Something which would be nice as well is to show the difference between the Applicative behaviour and the Semigroup behaviour, potentially in comparison with Either and Validated.

Something like :

import cats.data.{ IorNel, NonEmptyList, ValidatedNel }
import cats.implicits._

val oddOrEvenEither: Int => Either[Int, Int] = 
  n => Either.cond(n % 2 == 0, n, n)

val oddOrEvenValidatedNel: Int => ValidatedNel[Int, Int] =
  oddOrEven(_).toValidated.toValidatedNel

val oddOrEvenIorNel: Int => IorNel[Int, Int] =
  oddOrEven(_).toIor.leftMap(NonEmptyList.one)

type OddEither[A] = Either[Int, A]
type OddNelVal[A] = ValidatedNel[Int, A]
type OddNelIor[A] = IorNel[Int, A]

val nel = NonEmptyList.of(1, 2, 3, 4, 5)

// Ior short circuits like Either

nel.traverse[OddEither, Int](oddOrEvenEither)       // Left(1)
nel.traverse[OddNelVal, Int](oddOrEvenValidatedNel) // Invalid(NonEmptyList(1, List(3, 5)))
nel.traverse[OddNelIor, Int](oddOrEvenIorNel)       // Left(NonEmptyList(1, List()))

// for Either and Validated, Semigroup same result as with applicative
// but for Ior gives both sides

nel.reduceMap(oddOrEvenEither)        // Left(1)
nel.reduceMap(oddOrEvenValidatedNel)  // Invalid(NonEmptyList(1, List(3, 5)))
nel.reduceMap(oddOrEvenIorNel)        // Both(NonEmptyList(1, List(3, 5)), 6)

I can add this in a follow up PR if needed.

[ceedubs]

LGTM. @peterneyens are there any pending items you wanted to see make it into this before merging?

[peterneyens]

No, I'll follow up with another PR.