From d72e69b9cd540d8167f0f90bee759c8433d093ac Mon Sep 17 00:00:00 2001
From: Cody Allen <ceedubs@gmail.com>
Date: Fri, 15 Jul 2016 07:11:29 -0400
Subject: [PATCH] Add bisequence and bimap examples

This was originally part of #1194, but since it's looking uncertain
whether or not that will go forward, I'm separating it to here.
---
 core/src/main/scala/cats/Bitraverse.scala     | 27 ++++++++++++++++++-
 .../main/scala/cats/functor/Bifunctor.scala   |  9 +++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/core/src/main/scala/cats/Bitraverse.scala b/core/src/main/scala/cats/Bitraverse.scala
index 042e8b1e43..712f8ceade 100644
--- a/core/src/main/scala/cats/Bitraverse.scala
+++ b/core/src/main/scala/cats/Bitraverse.scala
@@ -6,10 +6,35 @@ import cats.functor.{Bifunctor, ComposedBifunctor}
  *  A type class abstracting over types that give rise to two independent [[cats.Traverse]]s.
  */
 trait Bitraverse[F[_, _]] extends Bifoldable[F] with Bifunctor[F] { self =>
+
   /** Traverse each side of the structure with the given functions */
   def bitraverse[G[_]: Applicative, A, B, C, D](fab: F[A, B])(f: A => G[C], g: B => G[D]): G[F[C, D]]
 
-  /** Sequence each side of the structure with the given functions */
+  /**
+   * Sequence each side of the structure with the given functions.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.data.Xor
+   * scala> import cats.implicits._
+   *
+   * scala> val rightSome: Option[String] Xor Option[Int] = Xor.right(Some(3))
+   * scala> rightSome.bisequence
+   * res0: Option[String Xor Int] = Some(Right(3))
+   *
+   * scala> val rightNone: Option[String] Xor Option[Int] = Xor.right(None)
+   * scala> rightNone.bisequence
+   * res0: Option[String Xor Int] = None
+   *
+   * scala> val leftSome: Option[String] Xor Option[Int] = Xor.left(Some("foo"))
+   * scala> leftSome.bisequence
+   * res0: Option[String Xor Int] = Some(Left(foo))
+   *
+   * scala> val leftNone: Option[String] Xor Option[Int] = Xor.left(None)
+   * scala> leftNone.bisequence
+   * res0: Option[String Xor Int] = None
+   * }}}
+   */
   def bisequence[G[_]: Applicative, A, B](fab: F[G[A], G[B]]): G[F[A, B]] =
     bitraverse(fab)(identity, identity)
 
diff --git a/core/src/main/scala/cats/functor/Bifunctor.scala b/core/src/main/scala/cats/functor/Bifunctor.scala
index 143505db84..1b20ab561a 100644
--- a/core/src/main/scala/cats/functor/Bifunctor.scala
+++ b/core/src/main/scala/cats/functor/Bifunctor.scala
@@ -10,6 +10,15 @@ trait Bifunctor[F[_, _]] extends Any with Serializable { self =>
   /**
    * The quintessential method of the Bifunctor trait, it applies a
    * function to each "side" of the bifunctor.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   *
+   * scala> val x: (List[String], Int) = (List("foo", "bar"), 3)
+   * scala> x.bimap(_.headOption, _.toLong + 1)
+   * res0: (Option[String], Long) = (Some(foo),4)
+   * }}}
    */
   def bimap[A, B, C, D](fab: F[A, B])(f: A => C, g: B => D): F[C, D]