Merge pull request #724 from ceedubs/doctest

Use SBT doctest plugin

build.sbt

@@ -18,6 +18,10 @@ lazy val buildSettings = Seq(
   crossScalaVersions := Seq("2.10.5", "2.11.7")
 )
 
+lazy val catsDoctestSettings = Seq(
+  doctestWithDependencies := false
+) ++ doctestSettings
+
 lazy val commonSettings = Seq(
   scalacOptions ++= commonScalacOptions,
   resolvers ++= Seq(
@@ -43,12 +47,16 @@ lazy val commonJsSettings = Seq(
 
 lazy val commonJvmSettings = Seq(
   testOptions in Test += Tests.Argument(TestFrameworks.ScalaTest, "-oDF")
-)
+// currently sbt-doctest doesn't work in JS builds, so this has to go in the
+// JVM settings. https://github.com/tkawachi/sbt-doctest/issues/52
+) ++ catsDoctestSettings
 
 lazy val catsSettings = buildSettings ++ commonSettings ++ publishSettings ++ scoverageSettings
 
+lazy val scalacheckVersion = "1.12.5"
+
 lazy val disciplineDependencies = Seq(
-  libraryDependencies += "org.scalacheck" %%% "scalacheck" % "1.12.5",
+  libraryDependencies += "org.scalacheck" %%% "scalacheck" % scalacheckVersion,
   libraryDependencies += "org.typelevel" %%% "discipline" % "0.4"
 )
 
@@ -122,6 +130,7 @@ lazy val core = crossProject.crossType(CrossType.Pure)
   .settings(
     sourceGenerators in Compile <+= (sourceManaged in Compile).map(Boilerplate.gen)
   )
+  .settings(libraryDependencies += "org.scalacheck" %%% "scalacheck" % scalacheckVersion % "test")
   .jsSettings(commonJsSettings:_*)
   .jvmSettings(commonJvmSettings:_*)
 
@@ -218,7 +227,7 @@ lazy val publishSettings = Seq(
 ) ++ credentialSettings ++ sharedPublishSettings ++ sharedReleaseProcess 
 
 // These aliases serialise the build for the benefit of Travis-CI.
-addCommandAlias("buildJVM", ";macrosJVM/compile;coreJVM/compile;freeJVM/compile;freeJVM/test;stateJVM/compile;stateJVM/test;lawsJVM/compile;testsJVM/test;jvm/test;bench/test")
+addCommandAlias("buildJVM", ";macrosJVM/compile;coreJVM/compile;coreJVM/test;freeJVM/compile;freeJVM/test;stateJVM/compile;stateJVM/test;lawsJVM/compile;testsJVM/test;jvm/test;bench/test")
 
 addCommandAlias("validateJVM", ";scalastyle;buildJVM;makeSite")
 

core/src/main/scala/cats/Foldable.scala

@@ -87,10 +87,15 @@ import simulacrum.typeclass
    * For example:
    *
    * {{{
-   *     def parseInt(s: String): Option[Int] = ...
-   *     val F = Foldable[List]
-   *     F.traverse_(List("333", "444"))(parseInt) // Some(())
-   *     F.traverse_(List("333", "zzz"))(parseInt) // None
+   * scala> import cats.data.Xor
+   * scala> import cats.std.list._
+   * scala> import cats.std.option._
+   * scala> def parseInt(s: String): Option[Int] = Xor.catchOnly[NumberFormatException](s.toInt).toOption
+   * scala> val F = Foldable[List]
+   * scala> F.traverse_(List("333", "444"))(parseInt)
+   * res0: Option[Unit] = Some(())
+   * scala> F.traverse_(List("333", "zzz"))(parseInt)
+   * res1: Option[Unit] = None
    * }}}
    *
    * This method is primarily useful when `G[_]` represents an action
@@ -111,9 +116,13 @@ import simulacrum.typeclass
    * For example:
    *
    * {{{
-   *     val F = Foldable[List]
-   *     F.sequence_(List(Option(1), Option(2), Option(3))) // Some(())
-   *     F.sequence_(List(Option(1), None, Option(3)))      // None
+   * scala> import cats.std.list._
+   * scala> import cats.std.option._
+   * scala> val F = Foldable[List]
+   * scala> F.sequence_(List(Option(1), Option(2), Option(3)))
+   * res0: Option[Unit] = Some(())
+   * scala> F.sequence_(List(Option(1), None, Option(3)))
+   * res1: Option[Unit] = None
    * }}}
    */
   def sequence_[G[_]: Applicative, A, B](fga: F[G[A]]): G[Unit] =
@@ -128,9 +137,10 @@ import simulacrum.typeclass
    * For example:
    *
    * {{{
-   *     val F = Foldable[List]
-   *     F.foldK(List(1 :: 2 :: Nil, 3 :: 4 :: 5 :: Nil))
-   *     // List(1, 2, 3, 4, 5)
+   * scala> import cats.std.list._
+   * scala> val F = Foldable[List]
+   * scala> F.foldK(List(1 :: 2 :: Nil, 3 :: 4 :: 5 :: Nil))
+   * res0: List[Int] = List(1, 2, 3, 4, 5)
    * }}}
    */
   def foldK[G[_], A](fga: F[G[A]])(implicit G: MonoidK[G]): G[A] =

core/src/main/scala/cats/data/OptionT.scala

@@ -108,8 +108,10 @@ object OptionT extends OptionTInstances {
    * Note: The return type is a FromOptionPartiallyApplied[F], which has an apply method
    * on it, allowing you to call fromOption like this:
    * {{{
-   * val t: Option[Int] = ...
-   * val x: OptionT[List, Int] = fromOption[List](t)
+   * scala> import cats.std.list._
+   * scala> val o: Option[Int] = Some(2)
+   * scala> OptionT.fromOption[List](o)
+   * res0: OptionT[List, Int] = OptionT(List(Some(2)))
    * }}}
    *
    * The reason for the indirection is to emulate currying type parameters.

core/src/main/scala/cats/data/Validated.scala

@@ -123,6 +123,12 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable {
    */
   def map[B](f: A => B): Validated[E,B] = bimap(identity, f)
 
+  /**
+   * Apply a function to an Invalid value, returning a new Invalid value.
+   * Or, if the original valid was Valid, return it.
+   */
+  def leftMap[EE](f: E => EE): Validated[EE,A] = bimap(f, identity)
+
   /**
    * When Valid, apply the function, marking the result as valid
    * inside the Applicative's context,
@@ -211,6 +217,7 @@ private[data] sealed abstract class ValidatedInstances extends ValidatedInstance
   implicit def validatedBifunctor: Bifunctor[Validated] =
     new Bifunctor[Validated] {
       override def bimap[A, B, C, D](fab: Validated[A, B])(f: A => C, g: B => D): Validated[C, D] = fab.bimap(f, g)
+      override def leftMap[A, B, C](fab: Validated[A, B])(f: A => C): Validated[C, B] = fab.leftMap(f)
     }
 
   implicit def validatedInstances[E](implicit E: Semigroup[E]): Traverse[Validated[E, ?]] with Applicative[Validated[E, ?]] =
@@ -267,8 +274,10 @@ trait ValidatedFunctions {
    * Evaluates the specified block, catching exceptions of the specified type and returning them on the invalid side of
    * the resulting `Validated`. Uncaught exceptions are propagated.
    *
-   * For example: {{{
-   * val result: Validated[NumberFormatException, Int] = catchOnly[NumberFormatException] { "foo".toInt }
+   * For example:
+   * {{{
+   * scala> Validated.catchOnly[NumberFormatException] { "foo".toInt }
+   * res0: Validated[NumberFormatException, Int] = Invalid(java.lang.NumberFormatException: For input string: "foo")
    * }}}
    */
   def catchOnly[T >: Null <: Throwable]: CatchOnlyPartiallyApplied[T] = new CatchOnlyPartiallyApplied[T]

core/src/main/scala/cats/data/Xor.scala

@@ -222,8 +222,10 @@ trait XorFunctions {
    * Evaluates the specified block, catching exceptions of the specified type and returning them on the left side of
    * the resulting `Xor`. Uncaught exceptions are propagated.
    *
-   * For example: {{{
-   * val result: NumberFormatException Xor Int = catchOnly[NumberFormatException] { "foo".toInt }
+   * For example:
+   * {{{
+   * scala> Xor.catchOnly[NumberFormatException] { "foo".toInt }
+   * res0: Xor[NumberFormatException, Int] = Left(java.lang.NumberFormatException: For input string: "foo")
    * }}}
    */
   def catchOnly[T >: Null <: Throwable]: CatchOnlyPartiallyApplied[T] =

core/src/main/scala/cats/data/XorT.scala

@@ -118,12 +118,15 @@ final case class XorT[F[_], A, B](value: F[A Xor B]) {
    *
    * Example:
    * {{{
-   * val v1: Validated[NonEmptyList[Error], Int] = ...
-   * val v2: Validated[NonEmptyList[Error], Int] = ...
-   * val xort: XorT[Error, Int] = ...
-   *
-   * val result: XorT[NonEmptyList[Error], Int] =
-   *   xort.withValidated { v3 => (v1 |@| v2 |@| v3.leftMap(NonEmptyList(_))) { case (i, j, k) => i + j + k } }
+   * scala> import cats.std.option._
+   * scala> import cats.std.list._
+   * scala> import cats.syntax.apply._
+   * scala> type Error = String
+   * scala> val v1: Validated[NonEmptyList[Error], Int] = Validated.Invalid(NonEmptyList("error 1"))
+   * scala> val v2: Validated[NonEmptyList[Error], Int] = Validated.Invalid(NonEmptyList("error 2"))
+   * scala> val xort: XorT[Option, Error, Int] = XorT(Some(Xor.left("error 3")))
+   * scala> xort.withValidated { v3 => (v1 |@| v2 |@| v3.leftMap(NonEmptyList(_))).map{ case (i, j, k) => i + j + k } }
+   * res0: XorT[Option, NonEmptyList[Error], Int] = XorT(Some(Left(OneAnd(error 1,List(error 2, error 3)))))
    * }}}
    */
   def withValidated[AA, BB](f: Validated[A, B] => Validated[AA, BB])(implicit F: Functor[F]): XorT[F, AA, BB] =
@@ -146,8 +149,10 @@ trait XorTFunctions {
    * Note: The return type is a FromXorPartiallyApplied[F], which has an apply method
    * on it, allowing you to call fromXor like this:
    * {{{
-   * val t: Xor[String, Int] = ...
-   * val x: XorT[Option, String, Int] = fromXor[Option](t)
+   * scala> import cats.std.option._
+   * scala> val t: Xor[String, Int] = Xor.right(3)
+   * scala> XorT.fromXor[Option](t)
+   * res0: XorT[Option, String, Int] = XorT(Some(Right(3)))
    * }}}
    *
    * The reason for the indirection is to emulate currying type parameters.

core/src/main/scala/cats/syntax/flatMap.scala

@@ -34,7 +34,13 @@ final class FlatMapOps[F[_], A](fa: F[A])(implicit F: FlatMap[F]) {
    * you can evaluate it only ''after'' the first action has finished:
    *
    * {{{
-   *   fa.followedByEval(later(fb))
+   * scala> import cats.Eval
+   * scala> import cats.std.option._
+   * scala> import cats.syntax.flatMap._
+   * scala> val fa: Option[Int] = Some(3)
+   * scala> def fb: Option[String] = Some("foo")
+   * scala> fa.followedByEval(Eval.later(fb))
+   * res0: Option[String] = Some(foo)
    * }}}
    */
   def followedByEval[B](fb: Eval[F[B]]): F[B] = F.flatMap(fa)(_ => fb.value)

free/src/test/scala/cats/free/FreeTests.scala

@@ -73,7 +73,7 @@ sealed trait FreeTestsInstances {
   }
 
   implicit def freeArbitrary[F[_], A](implicit F: Arbitrary[F[A]], A: Arbitrary[A]): Arbitrary[Free[F, A]] =
-    Arbitrary(freeGen[F, A](6))
+    Arbitrary(freeGen[F, A](4))
 
   implicit def freeEq[S[_]: Monad, A](implicit SA: Eq[S[A]]): Eq[Free[S, A]] =
     new Eq[Free[S, A]] {

project/plugins.sbt

@@ -3,14 +3,15 @@ resolvers += Resolver.url(
     url("http://dl.bintray.com/content/tpolecat/sbt-plugin-releases"))(
         Resolver.ivyStylePatterns)
 
-addSbtPlugin("com.eed3si9n"      % "sbt-unidoc"             % "0.3.2")
-addSbtPlugin("com.github.gseitz" % "sbt-release"            % "1.0.0")
-addSbtPlugin("com.jsuereth"      % "sbt-pgp"                % "1.0.0")
-addSbtPlugin("com.typesafe.sbt"  % "sbt-ghpages"            % "0.5.3")
-addSbtPlugin("com.typesafe.sbt"  % "sbt-site"               % "0.8.1")
-addSbtPlugin("org.tpolecat"      % "tut-plugin"             % "0.4.0")
-addSbtPlugin("pl.project13.scala"% "sbt-jmh"                % "0.2.3")
-addSbtPlugin("org.scalastyle"    %% "scalastyle-sbt-plugin" % "0.6.0")
-addSbtPlugin("org.scoverage"     % "sbt-scoverage"          % "1.2.0")
-addSbtPlugin("com.typesafe.sbt"  % "sbt-git"                % "0.8.4")
-addSbtPlugin("org.scala-js"      % "sbt-scalajs"            % "0.6.5")
+addSbtPlugin("com.eed3si9n"        % "sbt-unidoc"             % "0.3.2")
+addSbtPlugin("com.github.gseitz"   % "sbt-release"            % "1.0.0")
+addSbtPlugin("com.jsuereth"        % "sbt-pgp"                % "1.0.0")
+addSbtPlugin("com.typesafe.sbt"    % "sbt-ghpages"            % "0.5.3")
+addSbtPlugin("com.typesafe.sbt"    % "sbt-site"               % "0.8.1")
+addSbtPlugin("org.tpolecat"        % "tut-plugin"             % "0.4.0")
+addSbtPlugin("pl.project13.scala"  % "sbt-jmh"                % "0.2.3")
+addSbtPlugin("org.scalastyle"      %% "scalastyle-sbt-plugin" % "0.6.0")
+addSbtPlugin("org.scoverage"       % "sbt-scoverage"          % "1.2.0")
+addSbtPlugin("com.typesafe.sbt"    % "sbt-git"                % "0.8.4")
+addSbtPlugin("org.scala-js"        % "sbt-scalajs"            % "0.6.5")
+addSbtPlugin("com.github.tkawachi" % "sbt-doctest"            % "0.3.5")