Add doctests for Semigroup, Group, and Monoid (#2523)

* Add doctests for Semigroup, Group, and Monoid

* Fix combineAll doctest

* add scalaCheck dependency

* fix doctests

build.sbt

@@ -337,6 +337,7 @@ lazy val kernel = crossProject(JSPlatform, JVMPlatform, NativePlatform)
   .settings(includeGeneratedSrc)
   .jsSettings(commonJsSettings)
   .jvmSettings(commonJvmSettings ++ mimaSettings("cats-kernel"))
+  .settings(libraryDependencies += "org.scalacheck" %%% "scalacheck" % scalaCheckVersion(scalaVersion.value) % "test")
 
 
 lazy val kernelJVM = kernel.jvm

kernel/src/main/scala/cats/kernel/Group.scala

@@ -11,13 +11,29 @@ trait Group[@sp(Int, Long, Float, Double) A] extends Any with Monoid[A] {
    * Find the inverse of `a`.
    *
    * `combine(a, inverse(a))` = `combine(inverse(a), a)` = `empty`.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.kernel.instances.int._
+   *
+   * scala> Group[Int].inverse(5)
+   * res0: Int = -5
+   * }}}
    */
   def inverse(a: A): A
 
   /**
    * Remove the element `b` from `a`.
    *
    * Equivalent to `combine(a, inverse(b))`
+   *
+   * Example:
+   * {{{
+   * scala> import cats.kernel.instances.int._
+   *
+   * scala> Group[Int].remove(5, 2)
+   * res0: Int = 3
+   * }}}
    */
   def remove(a: A, b: A): A = combine(a, inverse(b))
 

kernel/src/main/scala/cats/kernel/Monoid.scala

@@ -12,17 +12,51 @@ trait Monoid[@sp(Int, Long, Float, Double) A] extends Any with Semigroup[A] {
 
   /**
    * Return the identity element for this monoid.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.kernel.instances.int._
+   * scala> import cats.kernel.instances.string._
+   *
+   * scala> Monoid[String].empty
+   * res0: String = ""
+   *
+   * scala> Monoid[Int].empty
+   * res1: Int = 0
+   * }}}
    */
   def empty: A
 
   /**
    * Tests if `a` is the identity.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.kernel.instances.string._
+   *
+   * scala> Monoid[String].isEmpty("")
+   * res0: Boolean = true
+   *
+   * scala> Monoid[String].isEmpty("something")
+   * res1: Boolean = false
+   * }}}
    */
   def isEmpty(a: A)(implicit ev: Eq[A]): Boolean =
     ev.eqv(a, empty)
 
   /**
    * Return `a` appended to itself `n` times.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.kernel.instances.string._
+   *
+   * scala> Monoid[String].combineN("ha", 3)
+   * res0: String = hahaha
+   *
+   * scala> Monoid[String].combineN("ha", 0)
+   * res1: String = ""
+   * }}}
    */
   override def combineN(a: A, n: Int): A =
     if (n < 0) throw new IllegalArgumentException("Repeated combining for monoids must have n >= 0")
@@ -31,6 +65,17 @@ trait Monoid[@sp(Int, Long, Float, Double) A] extends Any with Semigroup[A] {
 
   /**
    * Given a sequence of `as`, sum them using the monoid and return the total.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.kernel.instances.string._
+   *
+   * scala> Monoid[String].combineAll(List("One ", "Two ", "Three"))
+   * res0: String = One Two Three
+   *
+   * scala> Monoid[String].combineAll(List.empty)
+   * res1: String = ""
+   * }}}
    */
   def combineAll(as: TraversableOnce[A]): A =
     as.foldLeft(empty)(combine)

kernel/src/main/scala/cats/kernel/Semigroup.scala

@@ -1,6 +1,6 @@
 package cats.kernel
 
-import scala.{ specialized => sp }
+import scala.{specialized => sp}
 import scala.annotation.tailrec
 /**
  * A semigroup is any set `A` with an associative operation (`combine`).
@@ -9,11 +9,36 @@ trait Semigroup[@sp(Int, Long, Float, Double) A] extends Any with Serializable {
 
   /**
    * Associative operation which combines two values.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.kernel.instances.string._
+   * scala> import cats.kernel.instances.int._
+   * scala> import cats.kernel.instances.option._
+   *
+   * scala> Semigroup[String].combine("Hello ", "World!")
+   * res0: String = Hello World!
+   *
+   * scala> Semigroup[Option[Int]].combine(None, Some(1))
+   * res1: Option[Int] = Some(1)
+   * }}}
    */
   def combine(x: A, y: A): A
 
   /**
    * Return `a` combined with itself `n` times.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.kernel.instances.int._
+   * scala> import cats.kernel.instances.string._
+   *
+   * scala> Semigroup[Int].combineN(1, 10)
+   * res0: Int = 10
+   *
+   * scala> Semigroup[String].combineN("ha", 3)
+   * res1: String = hahaha
+   * }}}
    */
   def combineN(a: A, n: Int): A =
     if (n <= 0) throw new IllegalArgumentException("Repeated combining for semigroups must have n > 0")
@@ -35,6 +60,17 @@ trait Semigroup[@sp(Int, Long, Float, Double) A] extends Any with Serializable {
    * Given a sequence of `as`, combine them and return the total.
    *
    * If the sequence is empty, returns None. Otherwise, returns Some(total).
+   *
+   * Example:
+   * {{{
+   * scala> import cats.kernel.instances.string._
+   *
+   * scala> Semigroup[String].combineAllOption(List("One ", "Two ", "Three"))
+   * res0: Option[String] = Some(One Two Three)
+   *
+   * scala> Semigroup[String].combineAllOption(List.empty)
+   * res1: Option[String] = None
+   * }}}
    */
   def combineAllOption(as: TraversableOnce[A]): Option[A] =
     cats.kernel.compat.TraversableOnce.reduceOption(as, combine)