Merge pull request #2427 from ceedubs/semigroupal-doctests

Add scaladoc example for Semigroupal.product

core/src/main/scala/cats/Semigroupal.scala

@@ -13,6 +13,32 @@ import simulacrum.typeclass
  * [[Semigroupal]] and [[Functor]] to illustrate this.
  */
 @typeclass trait Semigroupal[F[_]] {
+
+  /**
+   * Combine an `F[A]` and an `F[B]` into an `F[(A, B)]` that maintains the effects of both `fa` and `fb`.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   *
+   * scala> val noneInt: Option[Int] = None
+   * scala> val some3: Option[Int] = Some(3)
+   * scala> val noneString: Option[String] = None
+   * scala> val someFoo: Option[String] = Some("foo")
+   *
+   * scala> Semigroupal[Option].product(noneInt, noneString)
+   * res0: Option[(Int, String)] = None
+   *
+   * scala> Semigroupal[Option].product(noneInt, someFoo)
+   * res1: Option[(Int, String)] = None
+   *
+   * scala> Semigroupal[Option].product(some3, noneString)
+   * res2: Option[(Int, String)] = None
+   *
+   * scala> Semigroupal[Option].product(some3, someFoo)
+   * res3: Option[(Int, String)] = Some((3,foo))
+   * }}}
+   */
   def product[A, B](fa: F[A], fb: F[B]): F[(A, B)]
 }