Make documentation more usable about sealed-monad

[MateuszKubuszok]

Things that were most surprising initially to me, which I would highlight:

• there are 2 type params that describe some result type: Sealed[F, A, ADT] - A and ADT

  • A is an intermediate result type of sort
  • ADT is like a final result type

• ADT is used for handling errors, HOWEVER it is also used as a final result type when exiting the Sealed monad in run - therefore while most of the time ADT can be used for some error-only type, on run ADT is expected to be something which stores both errors and success values

• in a way it makes it similar to (a: L).tailRecM[R](... : L => F[Either[L, R]])'s parameters where L is intermediate result and R is final result

• however when we are thinking that Sealed is similar to EitherT then we might be surprised because EitherT[F, L, R] flatMaps/maps etc on right R value, while Sealed[F, A, ADT] on left A value

  • to add to confusion method names are borrowed from EitherT

• probably it would make more sense to use examples comparing it to Result<S, F> from Rust which has a success as the first and a failure as the second type parameter

• it would also make sense to show that intended usages for ADT is something like

  enum UserCreationResult:
    case Success
    case UserAlreadyExists(details: String)
    case InvalidEmail(details: String)

  which models all allowed outcomes for some business action

  • since such enums are sealed traits in Scala 2 it explains the Sealed name, but I haven't been able to make that connection for a long time

All in all use cases are pretty reasonable BUT do not match Cats conventions and without a proper explanation Cats' users might follow wrong intuitions.