Update deprecations to product{L,R} instead of ap{L,R} (#2121)

* Add grouping to scaladoc for arity methods This makes it so when you look at the `Applicative` scaladoc you don't have a bunch of `ap3`, `ap4`, etc noise mixed in with the more meaningful methods. Instead, the generated higher-arity methods show up in separate scaladoc groups below. To see the changes you can pull this branch, run `sbt unidoc` (you may need to clean first), and open `cats/docs/target/scala-2.12/unidoc/cats/Applicative.html` in your browser. * Add doctest examples for Apply (#2086) * Get ready for RC2 (#2044) * Draft release notes * Update * Update * Update * Update * Update * Update Authors * Update * Update * Update * Update * update * Update * Update CHANGES.md * Update AUTHORS.md * Update README.md * Update deprecations to product{L,R} instead of ap{L,R}
typelevel · Dec 19, 2017 · d421663 · d421663
1 parent b702ddc
commit d421663
Show file tree

Hide file tree

Showing 9 changed files with 299 additions and 12 deletions.
diff --git a/AUTHORS.md b/AUTHORS.md
@@ -25,6 +25,7 @@ possible:
  * Alexey Levan
  * Alissa Pajer
  * Alistair Johnson
+ * Alonso Dominguez
  * Amir Mohammad Saied
  * Andrea Fiore
  * Andrew Jones
@@ -36,15 +37,19 @@ possible:
  * Aλ
  * Ben Fradet
  * Ben Hutchison
+ * Ben Kirwin
  * Benjamin Thuillier
  * Binh Nguyen
  * Bjørn Madsen
  * Bobby Rauchenberg
  * Brendan McAdams
  * Brian McKenna
  * Bryan Tan
+ * Cary Robbins
  * Chris Birchall
+ * Christopher Davenport
  * Cody Allen
+ * Colin Woodbury
  * Colt Frederickson
  * Connie Chen
  * Csongor Kiss
@@ -67,10 +72,13 @@ possible:
  * Erik LaBianca
  * Erik Osheim
  * Eugene Burmako
+ * Eugene Platonov
  * Eugene Yokota
+ * Fabian Gutierrez
  * Fabian Schmitthenner
  * Fabio Labella
  * Feynman Liang
+ * Filipe Oliveira
  * Frank S. Thomas
  * Gabriele Petronella
  * Giulio De Luise
@@ -83,6 +91,8 @@ possible:
  * Ionuț G. Stan
  * Israel Pérez González
  * Itamar Ravid
+ * Jacob Barber
+ * Jakub Kozłowski
  * Jan-Hendrik Zab
  * Jean-Rémi Desjardins
  * Jens
@@ -98,17 +108,19 @@ possible:
  * Julien Truffaut
  * Jun Tomioka
  * Kailuo Wang
+ * kellen
  * Kenji Yoshida
  * Leandro Bolivar
  * Lars Hupel
  * Long Cao
  * Luis Angel Vicente Sanchez
  * Luis Sanchez
- * LukaJCB
+ * Luka Jacobowitz
  * Luke Wyman
  * Madder
  * Marc Siegel
  * Marcin Rzeźnicki
+ * Marco Battaglia
  * Mark de Jong
  * Markus Hauck
  * mathhun
@@ -120,6 +132,7 @@ possible:
  * Michael Pilquist
  * Mike Curry
  * Miles Sabin
+ * nigredo-tori
  * n4to4
  * Olivier Blanvillain
  * Olli Helenius
@@ -146,6 +159,7 @@ possible:
  * Ross A. Baker
  * Rüdiger Klaehn
  * Ryan Case
+ * rsoeldner
  * Sam Ritchie
  * Sarunas Valaskevicius
  * Sho Kohara
@@ -155,8 +169,10 @@ possible:
  * Sinisa Louc
  * Stephen Carman
  * Stephen Judkins
+ * Stephen Lazaro
  * Stew O'Connor
  * Suhas Gaddam
+ * sullis
  * Sumedh Mungee
  * Takayuki Sakai
  * Taylor Brown

diff --git a/CHANGES.md b/CHANGES.md
@@ -1,3 +1,98 @@
+## Version 1.0.0-RC2
+
+> 2017 Nov 25
+
+### Breaking changes and migration
+
+* [#2039](https://github.com/typelevel/cats/pull/2039) Remove `Applicative#traverse` and `Applicative#sequence` by @kubukoz
+* [#2033](https://github.com/typelevel/cats/pull/2033) standardise on `liftF` and add `liftK` to transformers by @SystemFw
+* [#2083](https://github.com/typelevel/cats/pull/2083) Change forEffect/followedBy to productL/productR by @Jacoby6000
+* [#2088](https://github.com/typelevel/cats/pull/2088) Add `InvariantSemigroupal` and `ability` to turn `Monoidal`s to `Monoid`s by @LukaJCB
+
+### New features / enhancements (API, instances, data types, etc.):
+
+* [#1949](https://github.com/typelevel/cats/pull/1949) Add ::: to NonEmptyList by @jcranky
+* [#2020](https://github.com/typelevel/cats/pull/2020) Add `foldl` and `foldr` aliases to `Foldable` by @felixmulder
+* [#2024](https://github.com/typelevel/cats/pull/2024) Optimize foldMap implementations with combineAll by @carymrobbins
+* [#1938](https://github.com/typelevel/cats/pull/1938) Add more Parallel instances by @LukaJCB
+* [#2030](https://github.com/typelevel/cats/pull/2030) added `collectFirst` and `collectFirstSome` to `Foldable` by @kailuowang
+* [#1977](https://github.com/typelevel/cats/pull/1977) Add Ior Monad Transformer by @frroliveira
+* [#2038](https://github.com/typelevel/cats/pull/2038) Add &> and <& as syntax for Parallel by @LukaJCB
+* [#1981](https://github.com/typelevel/cats/pull/1981) Add UnorderedFoldable and UnorderedTraverse by @LukaJCB
+* [#2047](https://github.com/typelevel/cats/pull/2047) CommutativeMonoid instance for SortedMap by @alonsodomin
+* [#2043](https://github.com/typelevel/cats/pull/2043) Removed deprecation of >> and changed its param to be a by-name by @mpilquist
+* [#2034](https://github.com/typelevel/cats/pull/2034) Add ContravariantMonoidal by @stephen-lazaro
+* [#2057](https://github.com/typelevel/cats/pull/2057) Add `Ior.fromEither` by @markus1189
+* [#2056](https://github.com/typelevel/cats/pull/2056) Functor.fmap by @fosskers
+* [#2059](https://github.com/typelevel/cats/pull/2059) Add Parallel instance for Ior by @andyscott
+* [#2061](https://github.com/typelevel/cats/pull/2061) Add `MonadError.rethrow` by @SystemFw
+* [#2072](https://github.com/typelevel/cats/pull/2072) added a default id for Arrow by @kailuowang
+* [#2063](https://github.com/typelevel/cats/pull/2063) Added `merge` (product) to `Arrow` for arrows composition by @marcobattaglia
+* [#2060](https://github.com/typelevel/cats/pull/2060) Add parallel instance for IorT by @andyscott
+* [#2046](https://github.com/typelevel/cats/pull/2046) Add distributive typeclass and some instances by @coltfred
+* [#2099](https://github.com/typelevel/cats/pull/2099) CommutativeMonad and CommutativeFlatMap instances for Tuple2 by @ceedubs
+* [#2096](https://github.com/typelevel/cats/pull/2096) Add Arrow Choice by @stephen-lazaro
+* [#2098](https://github.com/typelevel/cats/pull/2098) Add a CommutativeMonoid for Map by @ceedubs
+* [#2101](https://github.com/typelevel/cats/pull/2101) Add Semigroup.instance method by @jozic
+* [#2103](https://github.com/typelevel/cats/pull/2103) CommutativeMonad for Eval by @ceedubs
+* [#2104](https://github.com/typelevel/cats/pull/2104) Add Commutative{Monad, FlatMap} instances for IdT by @ceedubs
+* [#2105](https://github.com/typelevel/cats/pull/2105) Some Kleisli instance cleanup by @ceedubs
+* [#2110](https://github.com/typelevel/cats/pull/2110) add `Comparison` to `cats` package by @kailuowang
+* [#2112](https://github.com/typelevel/cats/pull/2112) CoflatMap Instance for Applicative by @ChristopherDavenport
+* [#2116](https://github.com/typelevel/cats/pull/2116) conversion `PartialOrder` to `PartialOrdering` and `Hash` to `Hashing`  by @kailuowang
+* [#2100](https://github.com/typelevel/cats/pull/2100) Add `comparison` method in `Order` companion object by @ceedubs
+
+
+### Bug fixes:
+
+* [#2011](https://github.com/typelevel/cats/pull/2011) Rename ContravariantCartesian.scala to ContravariantSemigroupal.scala by @iravid
+* [#2016](https://github.com/typelevel/cats/pull/2016) Removed redundant Eq instance by @denisrosset
+* [#2029](https://github.com/typelevel/cats/pull/2029) make sure that EitherT MonadError syntax works the old way by @kailuowang
+
+
+### Documentation Improvements/Additions:
+
+* [#2007](https://github.com/typelevel/cats/pull/2007) move alleycats in readme by @kailuowang
+* [#2008](https://github.com/typelevel/cats/pull/2008) Upgrade Scalafix instructions by @gabro
+* [#2009](https://github.com/typelevel/cats/pull/2009) Correct it's -> its documentation errors by @kellen
+* [#2017](https://github.com/typelevel/cats/pull/2017) Fix alleycats module name by @benhutchison
+* [#2023](https://github.com/typelevel/cats/pull/2023) Fixes in Arrow docs by @Jasper-M
+* [#2026](https://github.com/typelevel/cats/pull/2026) Correctly close a tut:silent block in faq by @vendethiel
+* [#2027](https://github.com/typelevel/cats/pull/2027) Rename Validation to Validated in Validated docs by @Ttcao
+* [#2036](https://github.com/typelevel/cats/pull/2036) Clean up applicative syntax doc by @bkirwi
+* [#2035](https://github.com/typelevel/cats/pull/2035) Do not redirect to cats-mtl for MonadCombine by @vendethiel
+* [#2048](https://github.com/typelevel/cats/pull/2048) Add direct link to the scaladoc by @fagossa
+* [#2050](https://github.com/typelevel/cats/pull/2050) Link Directly to Cats Package in ScalaDoc by @stephen-lazaro
+* [#2031](https://github.com/typelevel/cats/pull/2031) Add parallel docs by @LukaJCB
+* [#2045](https://github.com/typelevel/cats/pull/2045) Fix scalafix testing instructions by @kubukoz
+* [#2068](https://github.com/typelevel/cats/pull/2068) Update symbols table by @stephen-lazaro
+* [#2070](https://github.com/typelevel/cats/pull/2070) Add some doctest examples for Alternative methods by @ceedubs
+* [#2065](https://github.com/typelevel/cats/pull/2065) added entry for sbt-catalysts by @kailuowang
+* [#2071](https://github.com/typelevel/cats/pull/2071) Add doc example for imap by @ceedubs
+* [#2073](https://github.com/typelevel/cats/pull/2073) Add doctests for `Ior.fromOptions` by @markus1189
+* [#2077](https://github.com/typelevel/cats/pull/2077) Add some doctest examples for SemigroupK/MonoidK by @ceedubs
+* [#2079](https://github.com/typelevel/cats/pull/2079) Add doctest examples for Applicative by @ceedubs
+* [#2095](https://github.com/typelevel/cats/pull/2095) Update guidelines.md by @kailuowang
+* [#2108](https://github.com/typelevel/cats/pull/2108) Update version of deprecation to 1.0.0-RC2 by @rossabaker
+
+
+### Build improvements/dependency updates
+
+* [#2028](https://github.com/typelevel/cats/pull/2028) Lawtesting: Update scalacheck-shapeless and cats by @vendethiel
+* [#2065](https://github.com/typelevel/cats/pull/2065) improve build by not displaying each success test by @kailuowang
+* [#2106](https://github.com/typelevel/cats/pull/2106) Update to latest patch versions of scala by @ceedubs
+* [#2114](https://github.com/typelevel/cats/pull/2114) sbt-coursier 1.0.0 by @sullis
+
+### Testing improvements
+
+* [#2037](https://github.com/typelevel/cats/pull/2037) Tests: MonadCombine->Alternative, add missing ones by @vendethiel 
+* [#2052](https://github.com/typelevel/cats/pull/2052) Add labels to prop produced from IsEq by @nigredo-tori
+* [#2053](https://github.com/typelevel/cats/pull/2053) Fix #2051, Remove superfluous implicit by @rsoeldner
+* [#2081](https://github.com/typelevel/cats/pull/2081) Reduce redundancy in Semigroup and Eq test names by @ceedubs
+* [#2097](https://github.com/typelevel/cats/pull/2097) added distributeIdentityLaw by @kailuowang
+
+
+
 ## Version 1.0.0-RC1
 
 > 2017 Oct 21 

diff --git a/README.md b/README.md
@@ -40,7 +40,7 @@ addSbtPlugin("org.lyranthe.sbt" % "partial-unification" % "1.1.0")
 And then create the cats dependency, by adding the following to your `build.sbt`:
 
 ```scala
-libraryDependencies += "org.typelevel" %% "cats-core" % "1.0.0-RC1"
+libraryDependencies += "org.typelevel" %% "cats-core" % "1.0.0-RC2"
 ```
 
 This will pull in the cats-core module. If you require some other

diff --git a/build.sbt b/build.sbt
@@ -178,6 +178,7 @@ lazy val docSettings = Seq(
   fork in (ScalaUnidoc, unidoc) := true,
   scalacOptions in (ScalaUnidoc, unidoc) ++= Seq(
     "-Xfatal-warnings",
+    "-groups",
     "-doc-source-url", scmInfo.value.get.browseUrl + "/tree/master€{FILE_PATH}.scala",
     "-sourcepath", baseDirectory.in(LocalRootProject).value.getAbsolutePath,
     "-diagrams"

diff --git a/core/src/main/scala/cats/Apply.scala b/core/src/main/scala/cats/Apply.scala
@@ -14,14 +14,97 @@ trait Apply[F[_]] extends Functor[F] with InvariantSemigroupal[F] with ApplyArit
   /**
    * Given a value and a function in the Apply context, applies the
    * function to the value.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   *
+   * scala> val someF: Option[Int => Long] = Some(_.toLong + 1L)
+   * scala> val noneF: Option[Int => Long] = None
+   * scala> val someInt: Option[Int] = Some(3)
+   * scala> val noneInt: Option[Int] = None
+   *
+   * scala> Apply[Option].ap(someF)(someInt)
+   * res0: Option[Long] = Some(4)
+   *
+   * scala> Apply[Option].ap(noneF)(someInt)
+   * res1: Option[Long] = None
+   *
+   * scala> Apply[Option].ap(someF)(noneInt)
+   * res2: Option[Long] = None
+   *
+   * scala> Apply[Option].ap(noneF)(noneInt)
+   * res3: Option[Long] = None
+   * }}}
    */
   def ap[A, B](ff: F[A => B])(fa: F[A]): F[B]
 
-  /** Compose two actions, discarding any value produced by the first. */
+  /**
+   * Compose two actions, discarding any value produced by the first.
+   *
+   * @see [[productL]] to discard the value of the second instead.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   * scala> import cats.data.Validated
+   * scala> import Validated.{Valid, Invalid}
+   *
+   * scala> type ErrOr[A] = Validated[String, A]
+   *
+   * scala> val validInt: ErrOr[Int] = Valid(3)
+   * scala> val validBool: ErrOr[Boolean] = Valid(true)
+   * scala> val invalidInt: ErrOr[Int] = Invalid("Invalid int.")
+   * scala> val invalidBool: ErrOr[Boolean] = Invalid("Invalid boolean.")
+   *
+   * scala> Apply[ErrOr].productR(validInt)(validBool)
+   * res0: ErrOr[Boolean] = Valid(true)
+   *
+   * scala> Apply[ErrOr].productR(invalidInt)(validBool)
+   * res1: ErrOr[Boolean] = Invalid(Invalid int.)
+   *
+   * scala> Apply[ErrOr].productR(validInt)(invalidBool)
+   * res2: ErrOr[Boolean] = Invalid(Invalid boolean.)
+   *
+   * scala> Apply[ErrOr].productR(invalidInt)(invalidBool)
+   * res3: ErrOr[Boolean] = Invalid(Invalid int.Invalid boolean.)
+   * }}}
+   *
+   */
   def productR[A, B](fa: F[A])(fb: F[B]): F[B] =
     map2(fa, fb)((_, b) => b)
 
-  /** Compose two actions, discarding any value produced by the second. */
+  /**
+   * Compose two actions, discarding any value produced by the second.
+   *
+   * @see [[productR]] to discard the value of the first instead.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   * scala> import cats.data.Validated
+   * scala> import Validated.{Valid, Invalid}
+   *
+   * scala> type ErrOr[A] = Validated[String, A]
+   *
+   * scala> val validInt: ErrOr[Int] = Valid(3)
+   * scala> val validBool: ErrOr[Boolean] = Valid(true)
+   * scala> val invalidInt: ErrOr[Int] = Invalid("Invalid int.")
+   * scala> val invalidBool: ErrOr[Boolean] = Invalid("Invalid boolean.")
+   *
+   * scala> Apply[ErrOr].productL(validInt)(validBool)
+   * res0: ErrOr[Int] = Valid(3)
+   *
+   * scala> Apply[ErrOr].productL(invalidInt)(validBool)
+   * res1: ErrOr[Int] = Invalid(Invalid int.)
+   *
+   * scala> Apply[ErrOr].productL(validInt)(invalidBool)
+   * res2: ErrOr[Int] = Invalid(Invalid boolean.)
+   *
+   * scala> Apply[ErrOr].productL(invalidInt)(invalidBool)
+   * res3: ErrOr[Int] = Invalid(Invalid int.Invalid boolean.)
+   * }}}
+   */
   def productL[A, B](fa: F[A])(fb: F[B]): F[A] =
     map2(fa, fb)((a, _) => a)
 
@@ -41,12 +124,12 @@ trait Apply[F[_]] extends Functor[F] with InvariantSemigroupal[F] with ApplyArit
     productL(fa)(fb)
 
   /** Alias for [[productR]]. */
-  @deprecated("Use *> or apR instead.", "1.0.0-RC2")
+  @deprecated("Use *> or productR instead.", "1.0.0-RC2")
   @noop @inline final def followedBy[A, B](fa: F[A])(fb: F[B]): F[B] =
     productR(fa)(fb)
 
   /** Alias for [[productL]]. */
-  @deprecated("Use <* or apL instead.", "1.0.0-RC2")
+  @deprecated("Use <* or productL instead.", "1.0.0-RC2")
   @noop @inline final def forEffect[A, B](fa: F[A])(fb: F[B]): F[A] =
     productL(fa)(fb)
 
@@ -60,6 +143,28 @@ trait Apply[F[_]] extends Functor[F] with InvariantSemigroupal[F] with ApplyArit
    * Applies the pure (binary) function f to the effectful values fa and fb.
    *
    * map2 can be seen as a binary version of [[cats.Functor]]#map.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   *
+   * scala> val someInt: Option[Int] = Some(3)
+   * scala> val noneInt: Option[Int] = None
+   * scala> val someLong: Option[Long] = Some(4L)
+   * scala> val noneLong: Option[Long] = None
+   *
+   * scala> Apply[Option].map2(someInt, someLong)((i, l) => i.toString + l.toString)
+   * res0: Option[String] = Some(34)
+   *
+   * scala> Apply[Option].map2(someInt, noneLong)((i, l) => i.toString + l.toString)
+   * res0: Option[String] = None
+   *
+   * scala> Apply[Option].map2(noneInt, noneLong)((i, l) => i.toString + l.toString)
+   * res0: Option[String] = None
+   *
+   * scala> Apply[Option].map2(noneInt, someLong)((i, l) => i.toString + l.toString)
+   * res0: Option[String] = None
+   * }}}
    */
   def map2[A, B, Z](fa: F[A], fb: F[B])(f: (A, B) => Z): F[Z] =
     map(product(fa, fb))(f.tupled)
@@ -89,6 +194,19 @@ trait Apply[F[_]] extends Functor[F] with InvariantSemigroupal[F] with ApplyArit
   def map2Eval[A, B, Z](fa: F[A], fb: Eval[F[B]])(f: (A, B) => Z): Eval[F[Z]] =
     fb.map(fb => map2(fa, fb)(f))
 
+  /**
+   * Compose an `Apply[F]` and an `Apply[G]` into an `Apply[λ[α => F[G[α]]]]`.
+   *
+   * Example:
+   * {{{
+   * scala> import cats.implicits._
+   *
+   * scala> val alo = Apply[List].compose[Option]
+   *
+   * scala> alo.product(List(None, Some(true), Some(false)), List(Some(2), None))
+   * res1: List[Option[(Boolean, Int)]] = List(None, None, Some((true,2)), None, Some((false,2)), None)
+   * }}}
+   */
   def compose[G[_]: Apply]: Apply[λ[α => F[G[α]]]] =
     new ComposedApply[F, G] {
       val F = self

diff --git a/core/src/main/scala/cats/FlatMap.scala b/core/src/main/scala/cats/FlatMap.scala
@@ -58,7 +58,7 @@ import simulacrum.noop
    */
   def productREval[A, B](fa: F[A])(fb: Eval[F[B]]): F[B] = flatMap(fa)(_ => fb.value)
 
-  @deprecated("Use apREval instead.", "1.0.0-RC2")
+  @deprecated("Use productREval instead.", "1.0.0-RC2")
   @noop def followedByEval[A, B](fa: F[A])(fb: Eval[F[B]]): F[B] = productREval(fa)(fb)
 
 
@@ -84,7 +84,7 @@ import simulacrum.noop
    */
   def productLEval[A, B](fa: F[A])(fb: Eval[F[B]]): F[A] = flatMap(fa)(a => map(fb.value)(_ => a))
 
-  @deprecated("Use apLEval instead.", "1.0.0-RC2")
+  @deprecated("Use productLEval instead.", "1.0.0-RC2")
   @noop def forEffectEval[A, B](fa: F[A])(fb: Eval[F[B]]): F[A] = productLEval(fa)(fb)
 
   override def ap[A, B](ff: F[A => B])(fa: F[A]): F[B] =