Use SBT doctest plugin

[ceedubs]

This helps ensure that our ScalaDoc examples actually compile and
produce the expected result.

[ceedubs]

Resolves #487.

I think the only example I haven't converted is one in MonadState. This type class is part of core, but the example uses StateT which is in a separate module. I don't think there is a way to make the core tests depend on the state module, since the state module depends on core. If someone knows how to make that work, it would be great.

[ceedubs]

@fthomas would you be willing to review since you know doctest well? I'd also be interested in any input from @tpolecat, since you are great with docs and user-friendliness.

[mpilquist]

@ceedubs Are we still considering collapsing free and state in to core?

[ceedubs]

@mpilquist I haven't heard that come up recently. It does seem a little odd to me that StateT is currently in its own module but WriterT isn't (see #573). I haven't yet found myself really wishing that Free and State were in core (as I did with std back when it was separate), but I also haven't used Cats "in the real world" yet.

[ceedubs]

The builds failed. My guess is that it's because doctest brought in its own version of Scalacheck and I need to be explicit about using our version. I'll look into it.

[fthomas]

Since we are explicitly using ScalaCheck it is a good idea to not let sbt-doctest add ScalaCheck as a dependency with doctestWithDependencies := false, see https://github.com/tkawachi/sbt-doctest#note-for-librarydependencies

[codecov-io]

Current coverage is 85.81%

Merging #724 into master will increase coverage by +0.23% as of 6a54f0a

@@            master    #724   diff @@
======================================
  Files          162     162       
  Stmts         2247    2249     +2
  Branches        74      74       
  Methods          0       0       
======================================
+ Hit           1923    1930     +7
  Partial          0       0       
+ Missed         324     319     -5

Review entire Coverage Diff as of 6a54f0a

Powered by Codecov. Updated on successful CI builds.

[fthomas]

I don't see any doctest output in the build log. I think we need to add coreJVM/test to the buildJVM alias.

[adelbertc]

This is awesome!

[ceedubs]

Wow, good eye, @fthomas. It should be fixed now.

[tpolecat]

This looks great. Makes me think how nice things would be if Travis were able to publish doc ... somewhere ... so reading doc in its final form could be part of the PR review process.

[ceedubs]

Okay I think this is good now. I see the following in the Travis build output:

[info] + Validated.scala.catchOnly.example at line 279: Validated.catchOnly[NumberFormatException] { "foo".toInt }: OK, proved property.
[info] + Xor.scala.catchOnly.example at line 227: Xor.catchOnly[NumberFormatException] { "foo".toInt }: OK, proved property.
[info] + OptionT.scala.fromOption.example at line 113: OptionT.fromOption[List](o): OK, proved property.
[info] + flatMap.scala.followedByEval.example at line 42: fa.followedByEval(Eval.later(fb)): OK, proved property.
[info] + XorT.scala.withValidated.example at line 130: xort.withValidated { v3 => (v1 |@| v2 |@| v3.leftMap(NonEmpt ...: OK, proved property.
[info] + XorT.scala.fromXor.example at line 156: XorT.fromXor[Option](t): OK, proved property.
[info] + Foldable.scala.traverse_.example at line 95: F.traverse_(List("333", "444"))(parseInt): OK, proved property.
[info] + Foldable.scala.traverse_.example at line 97: F.traverse_(List("333", "zzz"))(parseInt): OK, proved property.
[info] + Foldable.scala.foldK.example at line 142: F.foldK(List(1 :: 2 :: Nil, 3 :: 4 :: 5 :: Nil)): OK, proved property.
[info] + Foldable.scala.sequence_.example at line 122: F.sequence_(List(Option(1), Option(2), Option(3))): OK, proved property.
[info] + Foldable.scala.sequence_.example at line 124: F.sequence_(List(Option(1), None, Option(3))): OK, proved property.

[fthomas]

👍 Great work, @ceedubs! I particular like that this shows which imports are necessary to bring the various instances into scope. Leaving out imports in examples can be frustrating for beginners and annoying for experts.

[ceedubs]

It sounds like there is general approval, so I'm going to go ahead and merge (in part because I'm hoping the changes to the Arbitrary instance for Free fix builds that are failing). I'm happy to make some followup changes if people have any to suggest.