diff --git a/.scalafmt.conf b/.scalafmt.conf index f748649de6..f5f9a98895 100644 --- a/.scalafmt.conf +++ b/.scalafmt.conf @@ -8,7 +8,7 @@ danglingParentheses.preset = true rewrite.rules = [AvoidInfix, SortImports, RedundantParens, SortModifiers] docstrings = JavaDoc newlines.afterCurlyLambda = preserve -docstrings.style = keep +docstrings.style = Asterisk docstrings.oneline = unfold runner.dialect = scala213source3 diff --git a/algebra-core/src/main/scala/algebra/Priority.scala b/algebra-core/src/main/scala/algebra/Priority.scala index b48ab1f7a8..4d6c0334e3 100644 --- a/algebra-core/src/main/scala/algebra/Priority.scala +++ b/algebra-core/src/main/scala/algebra/Priority.scala @@ -26,13 +26,11 @@ import scala.annotation.nowarn /** * Priority is a type class for prioritized implicit search. * - * This type class will attempt to provide an implicit instance of `P` - * (the preferred type). If that type is not available it will - * fallback to `F` (the fallback type). If neither type is available - * then a `Priority[P, F]` instance will not be available. + * This type class will attempt to provide an implicit instance of `P` (the preferred type). If that type is not + * available it will fallback to `F` (the fallback type). If neither type is available then a `Priority[P, F]` instance + * will not be available. * - * This type can be useful for problems where multiple algorithms can - * be used, depending on the type classes available. + * This type can be useful for problems where multiple algorithms can be used, depending on the type classes available. */ sealed trait Priority[+P, +F] { diff --git a/algebra-core/src/main/scala/algebra/instances/StaticMethods.scala b/algebra-core/src/main/scala/algebra/instances/StaticMethods.scala index 18f0edf5cc..492f34c12f 100644 --- a/algebra-core/src/main/scala/algebra/instances/StaticMethods.scala +++ b/algebra-core/src/main/scala/algebra/instances/StaticMethods.scala @@ -28,8 +28,7 @@ object StaticMethods { /** * Exponentiation function, e.g. x^y * - * If base^ex doesn't fit in a Long, the result will overflow (unlike - * Math.pow which will return +/- Infinity). + * If base^ex doesn't fit in a Long, the result will overflow (unlike Math.pow which will return +/- Infinity). */ final def pow(base: Long, exponent: Long): Long = { @tailrec def loop(t: Long, b: Long, e: Long): Long = diff --git a/algebra-core/src/main/scala/algebra/instances/double.scala b/algebra-core/src/main/scala/algebra/instances/double.scala index c9f1fa6656..974ac65fbd 100644 --- a/algebra-core/src/main/scala/algebra/instances/double.scala +++ b/algebra-core/src/main/scala/algebra/instances/double.scala @@ -37,12 +37,11 @@ trait DoubleInstances extends cats.kernel.instances.DoubleInstances { } /** - * Due to the way floating-point equality works, this instance is not - * lawful under equality, but is correct when taken as an - * approximation of an exact value. + * Due to the way floating-point equality works, this instance is not lawful under equality, but is correct when taken + * as an approximation of an exact value. * - * If you would prefer an absolutely lawful fractional value, you'll - * need to investigate rational numbers or more exotic types. + * If you would prefer an absolutely lawful fractional value, you'll need to investigate rational numbers or more exotic + * types. */ class DoubleAlgebra extends Field[Double] with Serializable { diff --git a/algebra-core/src/main/scala/algebra/instances/float.scala b/algebra-core/src/main/scala/algebra/instances/float.scala index 80e6bcd39f..65d5eed968 100644 --- a/algebra-core/src/main/scala/algebra/instances/float.scala +++ b/algebra-core/src/main/scala/algebra/instances/float.scala @@ -36,12 +36,11 @@ trait FloatInstances extends cats.kernel.instances.FloatInstances { } /** - * Due to the way floating-point equality works, this instance is not - * lawful under equality, but is correct when taken as an - * approximation of an exact value. + * Due to the way floating-point equality works, this instance is not lawful under equality, but is correct when taken + * as an approximation of an exact value. * - * If you would prefer an absolutely lawful fractional value, you'll - * need to investigate rational numbers or more exotic types. + * If you would prefer an absolutely lawful fractional value, you'll need to investigate rational numbers or more exotic + * types. */ class FloatAlgebra extends Field[Float] with Serializable { diff --git a/algebra-core/src/main/scala/algebra/lattice/Bool.scala b/algebra-core/src/main/scala/algebra/lattice/Bool.scala index cae34de0cf..14edfd9206 100644 --- a/algebra-core/src/main/scala/algebra/lattice/Bool.scala +++ b/algebra-core/src/main/scala/algebra/lattice/Bool.scala @@ -26,23 +26,18 @@ import ring.BoolRing import scala.{specialized => sp} /** - * Boolean algebras are Heyting algebras with the additional - * constraint that the law of the excluded middle is true + * Boolean algebras are Heyting algebras with the additional constraint that the law of the excluded middle is true * (equivalently, double-negation is true). * - * This means that in addition to the laws Heyting algebras obey, - * boolean algebras also obey the following: + * This means that in addition to the laws Heyting algebras obey, boolean algebras also obey the following: * - * - (a ∨ ¬a) = 1 - * - ¬¬a = a + * - (a ∨ ¬a) = 1 + * - ¬¬a = a * - * Boolean algebras generalize classical logic: one is equivalent to - * "true" and zero is equivalent to "false". Boolean algebras provide - * additional logical operators such as `xor`, `nand`, `nor`, and - * `nxor` which are commonly used. + * Boolean algebras generalize classical logic: one is equivalent to "true" and zero is equivalent to "false". Boolean + * algebras provide additional logical operators such as `xor`, `nand`, `nor`, and `nxor` which are commonly used. * - * Every boolean algebras has a dual algebra, which involves reversing - * true/false as well as and/or. + * Every boolean algebras has a dual algebra, which involves reversing true/false as well as and/or. */ trait Bool[@sp(Int, Long) A] extends Any with Heyting[A] with GenBool[A] { self => def imp(a: A, b: A): A = or(complement(a), b) @@ -56,13 +51,12 @@ trait Bool[@sp(Int, Long) A] extends Any with Heyting[A] with GenBool[A] { self override def dual: Bool[A] = new DualBool(this) /** - * Every Boolean algebra is a BoolRing, with multiplication defined as - * `and` and addition defined as `xor`. Bool does not extend BoolRing - * because, e.g. we might want a Bool[Int] and CommutativeRing[Int] to - * refer to different structures, by default. + * Every Boolean algebra is a BoolRing, with multiplication defined as `and` and addition defined as `xor`. Bool does + * not extend BoolRing because, e.g. we might want a Bool[Int] and CommutativeRing[Int] to refer to different + * structures, by default. * - * Note that the ring returned by this method is not an extension of - * the `Rig` returned from `BoundedDistributiveLattice.asCommutativeRig`. + * Note that the ring returned by this method is not an extension of the `Rig` returned from + * `BoundedDistributiveLattice.asCommutativeRig`. */ override def asBoolRing: BoolRing[A] = new BoolRingFromBool(self) } @@ -89,11 +83,11 @@ class BoolRingFromBool[A](orig: Bool[A]) extends BoolRngFromGenBool(orig) with B /** * Every Boolean ring gives rise to a Boolean algebra: - * - 0 and 1 are preserved; - * - ring multiplication (`times`) corresponds to `and`; - * - ring addition (`plus`) corresponds to `xor`; - * - `a or b` is then defined as `a xor b xor (a and b)`; - * - complement (`¬a`) is defined as `a xor 1`. + * - 0 and 1 are preserved; + * - ring multiplication (`times`) corresponds to `and`; + * - ring addition (`plus`) corresponds to `xor`; + * - `a or b` is then defined as `a xor b xor (a and b)`; + * - complement (`¬a`) is defined as `a xor 1`. */ class BoolFromBoolRing[A](orig: BoolRing[A]) extends GenBoolFromBoolRng(orig) with Bool[A] { def one: A = orig.one diff --git a/algebra-core/src/main/scala/algebra/lattice/BoundedDistributiveLattice.scala b/algebra-core/src/main/scala/algebra/lattice/BoundedDistributiveLattice.scala index a439e993b2..098d6eb03b 100644 --- a/algebra-core/src/main/scala/algebra/lattice/BoundedDistributiveLattice.scala +++ b/algebra-core/src/main/scala/algebra/lattice/BoundedDistributiveLattice.scala @@ -34,8 +34,8 @@ trait BoundedDistributiveLattice[@sp(Int, Long, Float, Double) A] with DistributiveLattice[A] { self => /** - * Return a CommutativeRig using join and meet. Note this must obey the commutative rig laws since - * meet(a, one) = a, and meet and join are associative, commutative and distributive. + * Return a CommutativeRig using join and meet. Note this must obey the commutative rig laws since meet(a, one) = a, + * and meet and join are associative, commutative and distributive. */ private[algebra] def asCommutativeRig: CommutativeRig[A] = new CommutativeRig[A] { diff --git a/algebra-core/src/main/scala/algebra/lattice/BoundedLattice.scala b/algebra-core/src/main/scala/algebra/lattice/BoundedLattice.scala index c16e2b0a20..af9769eddf 100644 --- a/algebra-core/src/main/scala/algebra/lattice/BoundedLattice.scala +++ b/algebra-core/src/main/scala/algebra/lattice/BoundedLattice.scala @@ -25,17 +25,16 @@ package lattice import scala.{specialized => sp} /** - * A bounded lattice is a lattice that additionally has one element - * that is the bottom (zero, also written as ⊥), and one element that - * is the top (one, also written as ⊤). + * A bounded lattice is a lattice that additionally has one element that is the bottom (zero, also written as ⊥), and + * one element that is the top (one, also written as ⊤). * * This means that for any a in A: * - * join(zero, a) = a = meet(one, a) + * join(zero, a) = a = meet(one, a) * * Or written using traditional notation: * - * (0 ∨ a) = a = (1 ∧ a) + * (0 ∨ a) = a = (1 ∧ a) */ trait BoundedLattice[@sp(Int, Long, Float, Double) A] extends Any diff --git a/algebra-core/src/main/scala/algebra/lattice/DeMorgan.scala b/algebra-core/src/main/scala/algebra/lattice/DeMorgan.scala index 27da092d49..549c25b7dc 100644 --- a/algebra-core/src/main/scala/algebra/lattice/DeMorgan.scala +++ b/algebra-core/src/main/scala/algebra/lattice/DeMorgan.scala @@ -25,23 +25,19 @@ package lattice import scala.{specialized => sp} /** - * De Morgan algebras are bounded lattices that are also equipped with - * a De Morgan involution. + * De Morgan algebras are bounded lattices that are also equipped with a De Morgan involution. * * De Morgan involution obeys the following laws: * - * - ¬¬a = a - * - ¬(x∧y) = ¬x∨¬y + * - ¬¬a = a + * - ¬(x∧y) = ¬x∨¬y * - * However, in De Morgan algebras this involution does not necessarily - * provide the law of the excluded middle. This means that there is no - * guarantee that (a ∨ ¬a) = 1. De Morgan algebra do not not necessarily - * provide the law of non contradiction either. This means that there is - * no guarantee that (a ∧ ¬a) = 0. + * However, in De Morgan algebras this involution does not necessarily provide the law of the excluded middle. This + * means that there is no guarantee that (a ∨ ¬a) = 1. De Morgan algebra do not not necessarily provide the law of non + * contradiction either. This means that there is no guarantee that (a ∧ ¬a) = 0. * - * De Morgan algebras are useful to model fuzzy logic. For a model of - * classical logic, see the boolean algebra type class implemented as - * [[Bool]]. + * De Morgan algebras are useful to model fuzzy logic. For a model of classical logic, see the boolean algebra type + * class implemented as [[Bool]]. */ trait DeMorgan[@sp(Int, Long) A] extends Any with Logic[A] { self => def meet(a: A, b: A): A = and(a, b) @@ -64,8 +60,7 @@ object DeMorgan extends DeMorganFunctions[DeMorgan] { @inline final def apply[@sp(Int, Long) A](implicit ev: DeMorgan[A]): DeMorgan[A] = ev /** - * Turn a [[Bool]] into a `DeMorgan` - * Used for binary compatibility. + * Turn a [[Bool]] into a `DeMorgan` Used for binary compatibility. */ final def fromBool[@sp(Int, Long) A](bool: Bool[A]): DeMorgan[A] = new DeMorgan[A] { diff --git a/algebra-core/src/main/scala/algebra/lattice/GenBool.scala b/algebra-core/src/main/scala/algebra/lattice/GenBool.scala index ce535ff167..6f4798adb5 100644 --- a/algebra-core/src/main/scala/algebra/lattice/GenBool.scala +++ b/algebra-core/src/main/scala/algebra/lattice/GenBool.scala @@ -26,10 +26,8 @@ import ring.BoolRng import scala.{specialized => sp} /** - * Generalized Boolean algebra, that is, a Boolean algebra without - * the top element. Generalized Boolean algebras do not (in general) - * have (absolute) complements, but they have ''relative complements'' - * (see [[GenBool.without]]). + * Generalized Boolean algebra, that is, a Boolean algebra without the top element. Generalized Boolean algebras do not + * (in general) have (absolute) complements, but they have ''relative complements'' (see [[GenBool.without]]). */ trait GenBool[@sp(Int, Long) A] extends Any with DistributiveLattice[A] with BoundedJoinSemilattice[A] { self => def and(a: A, b: A): A @@ -39,21 +37,19 @@ trait GenBool[@sp(Int, Long) A] extends Any with DistributiveLattice[A] with Bou override def join(a: A, b: A): A = or(a, b) /** - * The operation of ''relative complement'', symbolically often denoted - * `a\b` (the symbol for set-theoretic difference, which is the - * meaning of relative complement in the lattice of sets). + * The operation of ''relative complement'', symbolically often denoted `a\b` (the symbol for set-theoretic + * difference, which is the meaning of relative complement in the lattice of sets). */ def without(a: A, b: A): A /** - * Logical exclusive or, set-theoretic symmetric difference. - * Defined as `a\b ∨ b\a`. + * Logical exclusive or, set-theoretic symmetric difference. Defined as `a\b ∨ b\a`. */ def xor(a: A, b: A): A = or(without(a, b), without(b, a)) /** - * Every generalized Boolean algebra is also a `BoolRng`, with - * multiplication defined as `and` and addition defined as `xor`. + * Every generalized Boolean algebra is also a `BoolRng`, with multiplication defined as `and` and addition defined as + * `xor`. */ @deprecated("See typelevel/algebra#108 for discussion", since = "2.7.0") def asBoolRing: BoolRng[A] = new BoolRngFromGenBool(self) @@ -61,15 +57,16 @@ trait GenBool[@sp(Int, Long) A] extends Any with DistributiveLattice[A] with Bou /** * Every Boolean rng gives rise to a Boolean algebra without top: - * - 0 is preserved; - * - ring multiplication (`times`) corresponds to `and`; - * - ring addition (`plus`) corresponds to `xor`; - * - `a or b` is then defined as `a xor b xor (a and b)`; - * - relative complement `a\b` is defined as `a xor (a and b)`. + * - 0 is preserved; + * - ring multiplication (`times`) corresponds to `and`; + * - ring addition (`plus`) corresponds to `xor`; + * - `a or b` is then defined as `a xor b xor (a and b)`; + * - relative complement `a\b` is defined as `a xor (a and b)`. * * `BoolRng.asBool.asBoolRing` gives back the original `BoolRng`. * - * @see [[algebra.lattice.GenBool.asBoolRing]] + * @see + * [[algebra.lattice.GenBool.asBoolRing]] */ class GenBoolFromBoolRng[A](orig: BoolRng[A]) extends GenBool[A] { def zero: A = orig.zero diff --git a/algebra-core/src/main/scala/algebra/lattice/Heyting.scala b/algebra-core/src/main/scala/algebra/lattice/Heyting.scala index 4afd255b2a..53ff7cf0f4 100644 --- a/algebra-core/src/main/scala/algebra/lattice/Heyting.scala +++ b/algebra-core/src/main/scala/algebra/lattice/Heyting.scala @@ -25,34 +25,28 @@ package lattice import scala.{specialized => sp} /** - * Heyting algebras are bounded lattices that are also equipped with - * an additional binary operation `imp` (for implication, also - * written as →). + * Heyting algebras are bounded lattices that are also equipped with an additional binary operation `imp` (for + * implication, also written as →). * * Implication obeys the following laws: * - * - a → a = 1 - * - a ∧ (a → b) = a ∧ b - * - b ∧ (a → b) = b - * - a → (b ∧ c) = (a → b) ∧ (a → c) + * - a → a = 1 + * - a ∧ (a → b) = a ∧ b + * - b ∧ (a → b) = b + * - a → (b ∧ c) = (a → b) ∧ (a → c) * - * In heyting algebras, `and` is equivalent to `meet` and `or` is - * equivalent to `join`; both methods are available. + * In heyting algebras, `and` is equivalent to `meet` and `or` is equivalent to `join`; both methods are available. * - * Heyting algebra also define `complement` operation (sometimes - * written as ¬a). The complement of `a` is equivalent to `(a → 0)`, - * and the following laws hold: + * Heyting algebra also define `complement` operation (sometimes written as ¬a). The complement of `a` is equivalent to + * `(a → 0)`, and the following laws hold: * - * - a ∧ ¬a = 0 + * - a ∧ ¬a = 0 * - * However, in Heyting algebras this operation is only a - * pseudo-complement, since Heyting algebras do not necessarily - * provide the law of the excluded middle. This means that there is no - * guarantee that (a ∨ ¬a) = 1. + * However, in Heyting algebras this operation is only a pseudo-complement, since Heyting algebras do not necessarily + * provide the law of the excluded middle. This means that there is no guarantee that (a ∨ ¬a) = 1. * - * Heyting algebras model intuitionistic logic. For a model of - * classical logic, see the boolean algebra type class implemented as - * `Bool`. + * Heyting algebras model intuitionistic logic. For a model of classical logic, see the boolean algebra type class + * implemented as `Bool`. */ trait Heyting[@sp(Int, Long) A] extends Any with BoundedDistributiveLattice[A] { self => def and(a: A, b: A): A diff --git a/algebra-core/src/main/scala/algebra/lattice/JoinSemilattice.scala b/algebra-core/src/main/scala/algebra/lattice/JoinSemilattice.scala index 13219a4952..f4ba487933 100644 --- a/algebra-core/src/main/scala/algebra/lattice/JoinSemilattice.scala +++ b/algebra-core/src/main/scala/algebra/lattice/JoinSemilattice.scala @@ -25,9 +25,8 @@ package lattice import scala.{specialized => sp} /** - * A join-semilattice (or upper semilattice) is a semilattice whose - * operation is called "join", and which can be thought of as a least - * upper bound. + * A join-semilattice (or upper semilattice) is a semilattice whose operation is called "join", and which can be thought + * of as a least upper bound. */ trait JoinSemilattice[@sp(Int, Long, Float, Double) A] extends Any with Serializable { def join(lhs: A, rhs: A): A diff --git a/algebra-core/src/main/scala/algebra/lattice/Lattice.scala b/algebra-core/src/main/scala/algebra/lattice/Lattice.scala index f04e94c067..0880575205 100644 --- a/algebra-core/src/main/scala/algebra/lattice/Lattice.scala +++ b/algebra-core/src/main/scala/algebra/lattice/Lattice.scala @@ -25,18 +25,15 @@ package lattice import scala.{specialized => sp} /** - * A lattice is a set `A` together with two operations (meet and - * join). Both operations individually constitute semilattices (join- - * and meet-semilattices respectively): each operation is commutative, - * associative, and idempotent. + * A lattice is a set `A` together with two operations (meet and join). Both operations individually constitute + * semilattices (join- and meet-semilattices respectively): each operation is commutative, associative, and idempotent. * - * Join can be thought of as finding a least upper bound (supremum), - * and meet can be thought of as finding a greatest lower bound - * (infimum). + * Join can be thought of as finding a least upper bound (supremum), and meet can be thought of as finding a greatest + * lower bound (infimum). * * The join and meet operations are also linked by absorption laws: * - * meet(a, join(a, b)) = join(a, meet(a, b)) = a + * meet(a, join(a, b)) = join(a, meet(a, b)) = a */ trait Lattice[@sp(Int, Long, Float, Double) A] extends Any with JoinSemilattice[A] with MeetSemilattice[A] { self => diff --git a/algebra-core/src/main/scala/algebra/lattice/Logic.scala b/algebra-core/src/main/scala/algebra/lattice/Logic.scala index b5b5380be6..e87dd6b301 100644 --- a/algebra-core/src/main/scala/algebra/lattice/Logic.scala +++ b/algebra-core/src/main/scala/algebra/lattice/Logic.scala @@ -25,15 +25,13 @@ package lattice import scala.{specialized => sp} /** - * Logic models a logic generally. It is a bounded distributive - * lattice with an extra negation operator. + * Logic models a logic generally. It is a bounded distributive lattice with an extra negation operator. * * The negation operator obeys the weak De Morgan laws: - * - ¬(x∨y) = ¬x∧¬y - * - ¬(x∧y) = ¬¬(¬x∨¬y) + * - ¬(x∨y) = ¬x∧¬y + * - ¬(x∧y) = ¬¬(¬x∨¬y) * - * For intuitionistic logic see [[Heyting]] - * For fuzzy logic see [[DeMorgan]] + * For intuitionistic logic see [[Heyting]] For fuzzy logic see [[DeMorgan]] */ trait Logic[@sp(Int, Long) A] extends Any with BoundedDistributiveLattice[A] { self => def and(a: A, b: A): A @@ -68,8 +66,7 @@ object Logic extends LogicFunctions[Logic] { @inline final def apply[@sp(Int, Long) A](implicit ev: Logic[A]): Logic[A] = ev /** - * Turn a [[Heyting]] into a `Logic`. - * Used for binary compatibility. + * Turn a [[Heyting]] into a `Logic`. Used for binary compatibility. */ final def fromHeyting[@sp(Int, Long) A](h: Heyting[A]): Logic[A] = new Logic[A] { diff --git a/algebra-core/src/main/scala/algebra/lattice/MeetSemilattice.scala b/algebra-core/src/main/scala/algebra/lattice/MeetSemilattice.scala index 02063093b0..9084bb381d 100644 --- a/algebra-core/src/main/scala/algebra/lattice/MeetSemilattice.scala +++ b/algebra-core/src/main/scala/algebra/lattice/MeetSemilattice.scala @@ -25,9 +25,8 @@ package lattice import scala.{specialized => sp} /** - * A meet-semilattice (or lower semilattice) is a semilattice whose - * operation is called "meet", and which can be thought of as a - * greatest lower bound. + * A meet-semilattice (or lower semilattice) is a semilattice whose operation is called "meet", and which can be thought + * of as a greatest lower bound. */ trait MeetSemilattice[@sp(Int, Long, Float, Double) A] extends Any with Serializable { def meet(lhs: A, rhs: A): A diff --git a/algebra-core/src/main/scala/algebra/ring/Additive.scala b/algebra-core/src/main/scala/algebra/ring/Additive.scala index dba76626e1..b4619bc182 100644 --- a/algebra-core/src/main/scala/algebra/ring/Additive.scala +++ b/algebra-core/src/main/scala/algebra/ring/Additive.scala @@ -191,11 +191,9 @@ object AdditiveSemigroup extends AdditiveSemigroupFunctions[AdditiveSemigroup] { @inline final def apply[A](implicit ev: AdditiveSemigroup[A]): AdditiveSemigroup[A] = ev /** - * This method converts an additive instance into a generic - * instance. + * This method converts an additive instance into a generic instance. * - * Given an implicit `AdditiveSemigroup[A]`, this method returns a - * `Semigroup[A]`. + * Given an implicit `AdditiveSemigroup[A]`, this method returns a `Semigroup[A]`. */ @inline final def additive[A](implicit ev: AdditiveSemigroup[A]): Semigroup[A] = ev.additive @@ -205,11 +203,9 @@ object AdditiveCommutativeSemigroup extends AdditiveSemigroupFunctions[AdditiveC @inline final def apply[A](implicit ev: AdditiveCommutativeSemigroup[A]): AdditiveCommutativeSemigroup[A] = ev /** - * This method converts an additive instance into a generic - * instance. + * This method converts an additive instance into a generic instance. * - * Given an implicit `AdditiveCommutativeSemigroup[A]`, this method returns a - * `CommutativeSemigroup[A]`. + * Given an implicit `AdditiveCommutativeSemigroup[A]`, this method returns a `CommutativeSemigroup[A]`. */ @inline final def additive[A](implicit ev: AdditiveCommutativeSemigroup[A]): CommutativeSemigroup[A] = ev.additive @@ -219,11 +215,9 @@ object AdditiveMonoid extends AdditiveMonoidFunctions[AdditiveMonoid] { @inline final def apply[A](implicit ev: AdditiveMonoid[A]): AdditiveMonoid[A] = ev /** - * This method converts an additive instance into a generic - * instance. + * This method converts an additive instance into a generic instance. * - * Given an implicit `AdditiveMonoid[A]`, this method returns a - * `Monoid[A]`. + * Given an implicit `AdditiveMonoid[A]`, this method returns a `Monoid[A]`. */ @inline final def additive[A](implicit ev: AdditiveMonoid[A]): Monoid[A] = ev.additive @@ -233,11 +227,9 @@ object AdditiveCommutativeMonoid extends AdditiveMonoidFunctions[AdditiveCommuta @inline final def apply[A](implicit ev: AdditiveCommutativeMonoid[A]): AdditiveCommutativeMonoid[A] = ev /** - * This method converts an additive instance into a generic - * instance. + * This method converts an additive instance into a generic instance. * - * Given an implicit `AdditiveCommutativeMonoid[A]`, this method returns a - * `CommutativeMonoid[A]`. + * Given an implicit `AdditiveCommutativeMonoid[A]`, this method returns a `CommutativeMonoid[A]`. */ @inline final def additive[A](implicit ev: AdditiveCommutativeMonoid[A]): CommutativeMonoid[A] = ev.additive @@ -247,11 +239,9 @@ object AdditiveGroup extends AdditiveGroupFunctions[AdditiveGroup] { @inline final def apply[A](implicit ev: AdditiveGroup[A]): AdditiveGroup[A] = ev /** - * This method converts an additive instance into a generic - * instance. + * This method converts an additive instance into a generic instance. * - * Given an implicit `AdditiveGroup[A]`, this method returns a - * `Group[A]`. + * Given an implicit `AdditiveGroup[A]`, this method returns a `Group[A]`. */ @inline final def additive[A](implicit ev: AdditiveGroup[A]): Group[A] = ev.additive @@ -261,11 +251,9 @@ object AdditiveCommutativeGroup extends AdditiveGroupFunctions[AdditiveCommutati @inline final def apply[A](implicit ev: AdditiveCommutativeGroup[A]): AdditiveCommutativeGroup[A] = ev /** - * This method converts an additive instance into a generic - * instance. + * This method converts an additive instance into a generic instance. * - * Given an implicit `AdditiveCommutativeGroup[A]`, this method returns a - * `CommutativeGroup[A]`. + * Given an implicit `AdditiveCommutativeGroup[A]`, this method returns a `CommutativeGroup[A]`. */ @inline final def additive[A](implicit ev: AdditiveCommutativeGroup[A]): CommutativeGroup[A] = ev.additive diff --git a/algebra-core/src/main/scala/algebra/ring/BoolRing.scala b/algebra-core/src/main/scala/algebra/ring/BoolRing.scala index f2cc56c64c..e2c8b37190 100644 --- a/algebra-core/src/main/scala/algebra/ring/BoolRing.scala +++ b/algebra-core/src/main/scala/algebra/ring/BoolRing.scala @@ -23,12 +23,10 @@ package algebra package ring /** - * A Boolean ring is a ring whose multiplication is idempotent, that is - * `a⋅a = a` for all elements ''a''. This property also implies `a+a = 0` - * for all ''a'', and `a⋅b = b⋅a` (commutativity of multiplication). + * A Boolean ring is a ring whose multiplication is idempotent, that is `a⋅a = a` for all elements ''a''. This property + * also implies `a+a = 0` for all ''a'', and `a⋅b = b⋅a` (commutativity of multiplication). * - * Every Boolean ring is equivalent to a Boolean algebra. - * See `algebra.lattice.BoolFromBoolRing` for details. + * Every Boolean ring is equivalent to a Boolean algebra. See `algebra.lattice.BoolFromBoolRing` for details. */ trait BoolRing[A] extends Any with BoolRng[A] with CommutativeRing[A] diff --git a/algebra-core/src/main/scala/algebra/ring/BoolRng.scala b/algebra-core/src/main/scala/algebra/ring/BoolRng.scala index 72e986daac..c741768ca8 100644 --- a/algebra-core/src/main/scala/algebra/ring/BoolRng.scala +++ b/algebra-core/src/main/scala/algebra/ring/BoolRng.scala @@ -23,12 +23,10 @@ package algebra package ring /** - * A Boolean rng is a rng whose multiplication is idempotent, that is - * `a⋅a = a` for all elements ''a''. This property also implies `a+a = 0` - * for all ''a'', and `a⋅b = b⋅a` (commutativity of multiplication). + * A Boolean rng is a rng whose multiplication is idempotent, that is `a⋅a = a` for all elements ''a''. This property + * also implies `a+a = 0` for all ''a'', and `a⋅b = b⋅a` (commutativity of multiplication). * - * Every `BoolRng` is equivalent to `algebra.lattice.GenBool`. - * See `algebra.lattice.GenBoolFromBoolRng` for details. + * Every `BoolRng` is equivalent to `algebra.lattice.GenBool`. See `algebra.lattice.GenBoolFromBoolRng` for details. */ trait BoolRng[A] extends Any with CommutativeRng[A] { self => final override def negate(x: A): A = x diff --git a/algebra-core/src/main/scala/algebra/ring/DivisionRing.scala b/algebra-core/src/main/scala/algebra/ring/DivisionRing.scala index aa46eaba5a..6cb262b30e 100644 --- a/algebra-core/src/main/scala/algebra/ring/DivisionRing.scala +++ b/algebra-core/src/main/scala/algebra/ring/DivisionRing.scala @@ -28,10 +28,8 @@ trait DivisionRing[@sp(Byte, Short, Int, Long, Float, Double) A] extends Any wit self => /** - * This is implemented in terms of basic Ring ops. However, this is - * probably significantly less efficient than can be done with a - * specific type. So, it is recommended that this method be - * overridden. + * This is implemented in terms of basic Ring ops. However, this is probably significantly less efficient than can be + * done with a specific type. So, it is recommended that this method be overridden. * * This is possible because a Double is a rational number. */ diff --git a/algebra-core/src/main/scala/algebra/ring/EuclideanRing.scala b/algebra-core/src/main/scala/algebra/ring/EuclideanRing.scala index 7a66306cb0..9fc4a41310 100644 --- a/algebra-core/src/main/scala/algebra/ring/EuclideanRing.scala +++ b/algebra-core/src/main/scala/algebra/ring/EuclideanRing.scala @@ -28,17 +28,15 @@ import scala.{specialized => sp} /** * EuclideanRing implements a Euclidean domain. * - * The formal definition says that every euclidean domain A has (at - * least one) euclidean function f: A -> N (the natural numbers) where: + * The formal definition says that every euclidean domain A has (at least one) euclidean function f: A -> N (the natural + * numbers) where: * - * (for every x and non-zero y) x = yq + r, and r = 0 or f(r) < f(y). + * (for every x and non-zero y) x = yq + r, and r = 0 or f(r) < f(y). * - * This generalizes the Euclidean division of integers, where f represents - * a measure of length (or absolute value), and the previous equation - * represents finding the quotient and remainder of x and y. So: + * This generalizes the Euclidean division of integers, where f represents a measure of length (or absolute value), and + * the previous equation represents finding the quotient and remainder of x and y. So: * - * quot(x, y) = q - * mod(x, y) = r + * quot(x, y) = q mod(x, y) = r */ trait EuclideanRing[@sp(Int, Long, Float, Double) A] extends Any with GCDRing[A] { self => def euclideanFunction(a: A): BigInt diff --git a/algebra-core/src/main/scala/algebra/ring/GCDRing.scala b/algebra-core/src/main/scala/algebra/ring/GCDRing.scala index db76d6e236..40ec1b9f6c 100644 --- a/algebra-core/src/main/scala/algebra/ring/GCDRing.scala +++ b/algebra-core/src/main/scala/algebra/ring/GCDRing.scala @@ -27,23 +27,21 @@ import scala.{specialized => sp} /** * GCDRing implements a GCD ring. * - * For two elements x and y in a GCD ring, we can choose two elements d and m - * such that: + * For two elements x and y in a GCD ring, we can choose two elements d and m such that: * - * d = gcd(x, y) - * m = lcm(x, y) - * - * d * m = x * y + * - d = gcd(x, y) + * - m = lcm(x, y) + * - d * m = x * y * * Additionally, we require: * - * gcd(0, 0) = 0 - * lcm(x, 0) = lcm(0, x) = 0 + * - gcd(0, 0) = 0 + * - lcm(x, 0) = lcm(0, x) = 0 * * and commutativity: * - * gcd(x, y) = gcd(y, x) - * lcm(x, y) = lcm(y, x) + * - gcd(x, y) = gcd(y, x) + * - lcm(x, y) = lcm(y, x) */ trait GCDRing[@sp(Int, Long, Float, Double) A] extends Any with CommutativeRing[A] { def gcd(a: A, b: A)(implicit ev: Eq[A]): A diff --git a/algebra-core/src/main/scala/algebra/ring/Multiplicative.scala b/algebra-core/src/main/scala/algebra/ring/Multiplicative.scala index 5d2a234dc3..4b14cdb760 100644 --- a/algebra-core/src/main/scala/algebra/ring/Multiplicative.scala +++ b/algebra-core/src/main/scala/algebra/ring/Multiplicative.scala @@ -165,11 +165,9 @@ object MultiplicativeSemigroup extends MultiplicativeSemigroupFunctions[Multipli @inline final def apply[A](implicit ev: MultiplicativeSemigroup[A]): MultiplicativeSemigroup[A] = ev /** - * This method converts a multiplicative instance into a generic - * instance. + * This method converts a multiplicative instance into a generic instance. * - * Given an implicit `MultiplicativeSemigroup[A]`, this method returns - * a `Semigroup[A]`. + * Given an implicit `MultiplicativeSemigroup[A]`, this method returns a `Semigroup[A]`. */ @inline final def multiplicative[A](implicit ev: MultiplicativeSemigroup[A]): Semigroup[A] = ev.multiplicative @@ -181,11 +179,9 @@ object MultiplicativeCommutativeSemigroup extends MultiplicativeSemigroupFunctio ): MultiplicativeCommutativeSemigroup[A] = ev /** - * This method converts a multiplicative instance into a generic - * instance. + * This method converts a multiplicative instance into a generic instance. * - * Given an implicit `MultiplicativeCommutativeSemigroup[A]`, this method returns - * a `CommutativeSemigroup[A]`. + * Given an implicit `MultiplicativeCommutativeSemigroup[A]`, this method returns a `CommutativeSemigroup[A]`. */ @inline final def multiplicative[A](implicit ev: MultiplicativeCommutativeSemigroup[A]): CommutativeSemigroup[A] = ev.multiplicative @@ -195,11 +191,9 @@ object MultiplicativeMonoid extends MultiplicativeMonoidFunctions[Multiplicative @inline final def apply[A](implicit ev: MultiplicativeMonoid[A]): MultiplicativeMonoid[A] = ev /** - * This method converts a multiplicative instance into a generic - * instance. + * This method converts a multiplicative instance into a generic instance. * - * Given an implicit `MultiplicativeMonoid[A]`, this method returns - * a `Monoid[A]`. + * Given an implicit `MultiplicativeMonoid[A]`, this method returns a `Monoid[A]`. */ @inline final def multiplicative[A](implicit ev: MultiplicativeMonoid[A]): Monoid[A] = ev.multiplicative @@ -209,11 +203,9 @@ object MultiplicativeCommutativeMonoid extends MultiplicativeMonoidFunctions[Mul @inline final def apply[A](implicit ev: MultiplicativeCommutativeMonoid[A]): MultiplicativeCommutativeMonoid[A] = ev /** - * This method converts a multiplicative instance into a generic - * instance. + * This method converts a multiplicative instance into a generic instance. * - * Given an implicit `MultiplicativeCommutativeMonoid[A]`, this method returns - * a `CommutativeMonoid[A]`. + * Given an implicit `MultiplicativeCommutativeMonoid[A]`, this method returns a `CommutativeMonoid[A]`. */ @inline final def multiplicative[A](implicit ev: MultiplicativeCommutativeMonoid[A]): CommutativeMonoid[A] = ev.multiplicative @@ -223,11 +215,9 @@ object MultiplicativeGroup extends MultiplicativeGroupFunctions[MultiplicativeGr @inline final def apply[A](implicit ev: MultiplicativeGroup[A]): MultiplicativeGroup[A] = ev /** - * This method converts a multiplicative instance into a generic - * instance. + * This method converts a multiplicative instance into a generic instance. * - * Given an implicit `MultiplicativeGroup[A]`, this method returns - * a `Group[A]`. + * Given an implicit `MultiplicativeGroup[A]`, this method returns a `Group[A]`. */ @inline final def multiplicative[A](implicit ev: MultiplicativeGroup[A]): Group[A] = ev.multiplicative @@ -237,11 +227,9 @@ object MultiplicativeCommutativeGroup extends MultiplicativeGroupFunctions[Multi @inline final def apply[A](implicit ev: MultiplicativeCommutativeGroup[A]): MultiplicativeCommutativeGroup[A] = ev /** - * This method converts a multiplicative instance into a generic - * instance. + * This method converts a multiplicative instance into a generic instance. * - * Given an implicit `MultiplicativeCommutativeGroup[A]`, this method returns - * a `CommutativeGroup[A]`. + * Given an implicit `MultiplicativeCommutativeGroup[A]`, this method returns a `CommutativeGroup[A]`. */ @inline final def multiplicative[A](implicit ev: MultiplicativeCommutativeGroup[A]): CommutativeGroup[A] = ev.multiplicative diff --git a/algebra-core/src/main/scala/algebra/ring/Rig.scala b/algebra-core/src/main/scala/algebra/ring/Rig.scala index 04734999ea..836d13ae6f 100644 --- a/algebra-core/src/main/scala/algebra/ring/Rig.scala +++ b/algebra-core/src/main/scala/algebra/ring/Rig.scala @@ -27,11 +27,10 @@ import scala.{specialized => sp} /** * Rig consists of: * - * - a commutative monoid for addition (+) - * - a monoid for multiplication (*) + * - a commutative monoid for addition (+) + * - a monoid for multiplication (*) * - * Alternately, a Rig can be thought of as a ring without - * multiplicative or additive inverses (or as a semiring with a + * Alternately, a Rig can be thought of as a ring without multiplicative or additive inverses (or as a semiring with a * multiplicative identity). * * Mnemonic: "Rig is a Ring without 'N'egation." diff --git a/algebra-core/src/main/scala/algebra/ring/Ring.scala b/algebra-core/src/main/scala/algebra/ring/Ring.scala index f295b13153..78123c0121 100644 --- a/algebra-core/src/main/scala/algebra/ring/Ring.scala +++ b/algebra-core/src/main/scala/algebra/ring/Ring.scala @@ -28,15 +28,13 @@ import scala.annotation.tailrec /** * Ring consists of: * - * - a commutative group for addition (+) - * - a monoid for multiplication (*) + * - a commutative group for addition (+) + * - a monoid for multiplication (*) * * Additionally, multiplication must distribute over addition. * - * Ring implements some methods (for example fromInt) in terms of - * other more fundamental methods (zero, one and plus). Where - * possible, these methods should be overridden by more efficient - * implementations. + * Ring implements some methods (for example fromInt) in terms of other more fundamental methods (zero, one and plus). + * Where possible, these methods should be overridden by more efficient implementations. */ trait Ring[@sp(Int, Long, Float, Double) A] extends Any with Rig[A] with Rng[A] { @@ -45,22 +43,19 @@ trait Ring[@sp(Int, Long, Float, Double) A] extends Any with Rig[A] with Rng[A] * * Defined to be equivalent to `sumN(one, n)`. * - * That is, `n` repeated summations of this ring's `one`, or `-n` - * summations of `-one` if `n` is negative. + * That is, `n` repeated summations of this ring's `one`, or `-n` summations of `-one` if `n` is negative. * - * Most type class instances should consider overriding this method - * for performance reasons. + * Most type class instances should consider overriding this method for performance reasons. */ def fromInt(n: Int): A = sumN(one, n) /** * Convert the given BigInt to an instance of A. * - * This is equivalent to `n` repeated summations of this ring's `one`, or - * `-n` summations of `-one` if `n` is negative. + * This is equivalent to `n` repeated summations of this ring's `one`, or `-n` summations of `-one` if `n` is + * negative. * - * Most type class instances should consider overriding this method for - * performance reasons. + * Most type class instances should consider overriding this method for performance reasons. */ def fromBigInt(n: BigInt): A = Ring.defaultFromBigInt(n)(this) } @@ -93,12 +88,10 @@ trait RingFunctions[R[T] <: Ring[T]] extends AdditiveGroupFunctions[R] with Mult } /** - * Returns the given Double, understood as a rational number, in the provided - * (division) ring. + * Returns the given Double, understood as a rational number, in the provided (division) ring. * - * This is implemented in terms of basic ops. However, this is - * probably significantly less efficient than can be done with a specific - * type. So, it is recommended to specialize this general method. + * This is implemented in terms of basic ops. However, this is probably significantly less efficient than can be done + * with a specific type. So, it is recommended to specialize this general method. */ final def defaultFromDouble[A](a: Double)(implicit ringA: Ring[A], mgA: MultiplicativeGroup[A]): A = if (a == 0.0) ringA.zero diff --git a/algebra-core/src/main/scala/algebra/ring/Rng.scala b/algebra-core/src/main/scala/algebra/ring/Rng.scala index 19c668c2b3..3ec4d8b0f8 100644 --- a/algebra-core/src/main/scala/algebra/ring/Rng.scala +++ b/algebra-core/src/main/scala/algebra/ring/Rng.scala @@ -27,11 +27,10 @@ import scala.{specialized => sp} /** * Rng (pronounced "Rung") consists of: * - * - a commutative group for addition (+) - * - a semigroup for multiplication (*) + * - a commutative group for addition (+) + * - a semigroup for multiplication (*) * - * Alternately, a Rng can be thought of as a ring without a - * multiplicative identity (or as a semiring with an additive + * Alternately, a Rng can be thought of as a ring without a multiplicative identity (or as a semiring with an additive * inverse). * * Mnemonic: "Rng is a Ring without multiplicative 'I'dentity." diff --git a/algebra-core/src/main/scala/algebra/ring/Semifield.scala b/algebra-core/src/main/scala/algebra/ring/Semifield.scala index b19ef820b6..9c14f5da40 100644 --- a/algebra-core/src/main/scala/algebra/ring/Semifield.scala +++ b/algebra-core/src/main/scala/algebra/ring/Semifield.scala @@ -27,8 +27,8 @@ import scala.{specialized => sp} /** * Semifield consists of: * - * - a commutative monoid for addition (+) - * - a group for multiplication (*) + * - a commutative monoid for addition (+) + * - a group for multiplication (*) * * Alternately, a Semifield can be thought of as a DivisionRing without an additive inverse. */ diff --git a/algebra-core/src/main/scala/algebra/ring/Semiring.scala b/algebra-core/src/main/scala/algebra/ring/Semiring.scala index d389b3816f..041e9c9b2f 100644 --- a/algebra-core/src/main/scala/algebra/ring/Semiring.scala +++ b/algebra-core/src/main/scala/algebra/ring/Semiring.scala @@ -27,15 +27,13 @@ import scala.{specialized => sp} /** * Semiring consists of: * - * - a commutative monoid for addition (+) - * - a semigroup for multiplication (*) + * - a commutative monoid for addition (+) + * - a semigroup for multiplication (*) * - * Alternately, a Semiring can be thought of as a ring without a - * multiplicative identity or an additive inverse. + * Alternately, a Semiring can be thought of as a ring without a multiplicative identity or an additive inverse. * - * A Semiring with an additive inverse (-) is a Rng. - * A Semiring with a multiplicative identity (1) is a Rig. - * A Semiring with both of those is a Ring. + * A Semiring with an additive inverse (-) is a Rng. A Semiring with a multiplicative identity (1) is a Rig. A Semiring + * with both of those is a Ring. */ trait Semiring[@sp(Int, Long, Float, Double) A] extends Any diff --git a/algebra-core/src/main/scala/algebra/ring/Signed.scala b/algebra-core/src/main/scala/algebra/ring/Signed.scala index e7d3e1b061..3c9b582335 100644 --- a/algebra-core/src/main/scala/algebra/ring/Signed.scala +++ b/algebra-core/src/main/scala/algebra/ring/Signed.scala @@ -31,22 +31,22 @@ import scala.{specialized => sp} * * The following laws holds: * - * (1) if `a <= b` then `a + c <= b + c` (linear order), - * (2) `signum(x) = -1` if `x < 0`, `signum(x) = 1` if `x > 0`, `signum(x) = 0` otherwise, + * - (1) if `a <= b` then `a + c <= b + c` (linear order), + * - (2) `signum(x) = -1` if `x < 0`, `signum(x) = 1` if `x > 0`, `signum(x) = 0` otherwise, * * Negative elements only appear when the scalar is taken from a additive abelian group. Then: * - * (3) `abs(x) = -x` if `x < 0`, or `x` otherwise, + * - (3) `abs(x) = -x` if `x < 0`, or `x` otherwise, * * Laws (1) and (2) lead to the triange inequality: * - * (4) `abs(a + b) <= abs(a) + abs(b)` + * - (4) `abs(a + b) <= abs(a) + abs(b)` * * Signed should never be extended in implementations, rather the [[Signed.forAdditiveCommutativeMonoid]] and * [[Signed.forAdditiveCommutativeGroup subtraits]]. * - * It's better to have the Signed hierarchy separate from the Ring/Order hierarchy, so that - * we do not end up with duplicate implicits. + * It's better to have the Signed hierarchy separate from the Ring/Order hierarchy, so that we do not end up with + * duplicate implicits. */ trait Signed[@sp(Byte, Short, Int, Long, Float, Double) A] extends Any { diff --git a/algebra-core/src/main/scala/algebra/ring/TruncatedDivision.scala b/algebra-core/src/main/scala/algebra/ring/TruncatedDivision.scala index 5480cef689..81d1be9aae 100644 --- a/algebra-core/src/main/scala/algebra/ring/TruncatedDivision.scala +++ b/algebra-core/src/main/scala/algebra/ring/TruncatedDivision.scala @@ -24,32 +24,27 @@ package algebra.ring import scala.{specialized => sp} /** - * Division and modulus for computer scientists - * taken from https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/divmodnote-letter.pdf + * Division and modulus for computer scientists taken from + * https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/divmodnote-letter.pdf * - * For two numbers x (dividend) and y (divisor) on an ordered ring with y != 0, - * there exists a pair of numbers q (quotient) and r (remainder) - * such that these laws are satisfied: + * For two numbers `x` (dividend) and `y` (divisor) on an ordered ring with `y != 0`, there exists a pair of numbers `q` + * (quotient) and `r` (remainder) such that these laws are satisfied: * - * (1) q is an integer - * (2) x = y * q + r (division rule) - * (3) |r| < |y|, - * (4t) r = 0 or sign(r) = sign(x), - * (4f) r = 0 or sign(r) = sign(y). + * - (1) `q` is an integer + * - (2) `x = y * q + r` (division rule) + * - (3) `|r| < |y|`, + * - (4t) `r = 0` or `sign(r) = sign(x)`, + * - (4f) `r = 0` or `sign(r) = sign(y)`. * - * where sign is the sign function, and the absolute value - * function |x| is defined as |x| = x if x >=0, and |x| = -x otherwise. + * where `sign` is the sign function, and the absolute value function `|x|` is defined as `|x| = x` if `x >=0`, and + * `|x| = -x` otherwise. * - * We define functions tmod and tquot such that: - * q = tquot(x, y) and r = tmod(x, y) obey rule (4t), - * (which truncates effectively towards zero) - * and functions fmod and fquot such that: - * q = fquot(x, y) and r = fmod(x, y) obey rule (4f) - * (which floors the quotient and effectively rounds towards negative infinity). + * We define functions `tmod` and `tquot` such that: `q = tquot(x, y)` and `r = tmod(x, y)` obey rule (4t), (which + * truncates effectively towards zero) and functions `fmod` and `fquot` such that: `q = fquot(x, y)` and + * `r = fmod(x, y)` obey rule (4f) (which floors the quotient and effectively rounds towards negative infinity). * - * Law (4t) corresponds to ISO C99 and Haskell's quot/rem. - * Law (4f) is described by Knuth and used by Haskell, - * and fmod corresponds to the REM function of the IEEE floating-point standard. + * Law (4t) corresponds to ISO C99 and Haskell's quot/rem. Law (4f) is described by Knuth and used by Haskell, and fmod + * corresponds to the REM function of the IEEE floating-point standard. */ trait TruncatedDivision[@sp(Byte, Short, Int, Long, Float, Double) A] extends Any with Signed[A] { def tquot(x: A, y: A): A diff --git a/algebra-laws/shared/src/main/scala/algebra/laws/CheckSupport.scala b/algebra-laws/shared/src/main/scala/algebra/laws/CheckSupport.scala index f67ba3cc0a..71ba3c06e6 100644 --- a/algebra-laws/shared/src/main/scala/algebra/laws/CheckSupport.scala +++ b/algebra-laws/shared/src/main/scala/algebra/laws/CheckSupport.scala @@ -22,12 +22,10 @@ package algebra.laws /** - * This object contains Arbitrary instances for types defined in - * algebra.instances, as well as anything else we'd like to import to assist - * in running ScalaCheck tests. + * This object contains Arbitrary instances for types defined in algebra.instances, as well as anything else we'd like + * to import to assist in running ScalaCheck tests. * - * (Since algebra-instances has no dependencies, its types can't - * define Arbitrary instances in companions.) + * (Since algebra-instances has no dependencies, its types can't define Arbitrary instances in companions.) */ @deprecated("No replacement", since = "2.7.0") object CheckSupport {} diff --git a/algebra-laws/shared/src/test/scala/algebra/laws/FPApprox.scala b/algebra-laws/shared/src/test/scala/algebra/laws/FPApprox.scala index c91ddad5cb..b9bb4d866a 100644 --- a/algebra-laws/shared/src/test/scala/algebra/laws/FPApprox.scala +++ b/algebra-laws/shared/src/test/scala/algebra/laws/FPApprox.scala @@ -30,14 +30,12 @@ import algebra.* import algebra.ring.* /** - * A wrapper type for approximate floating point values like Float, Double, and - * BigDecimal which maintains an error bound on the current approximation. The - * `Eq` instance for this type returns true if 2 values could be equal to each - * other, given the error bounds, rather than if they actually are equal. So, - * if x == 0.5, and y = 0.6, and the error bound of (x - y) is greater than or - * equal to 0.1, then it's plausible they could be equal to each other, so we - * return true. On the other hand, if the error bound is less than 0.1, then we - * can definitely say they cannot be equal to each other. + * A wrapper type for approximate floating point values like Float, Double, and BigDecimal which maintains an error + * bound on the current approximation. The `Eq` instance for this type returns true if 2 values could be equal to each + * other, given the error bounds, rather than if they actually are equal. So, if x == 0.5, and y = 0.6, and the error + * bound of (x - y) is greater than or equal to 0.1, then it's plausible they could be equal to each other, so we return + * true. On the other hand, if the error bound is less than 0.1, then we can definitely say they cannot be equal to each + * other. */ case class FPApprox[A](approx: A, mes: A, ind: BigInt) { import FPApprox.{abs, Epsilon} diff --git a/algebra-laws/shared/src/test/scala/algebra/laws/SimpleDeMorgan.scala b/algebra-laws/shared/src/test/scala/algebra/laws/SimpleDeMorgan.scala index a11b503a50..1fda695059 100644 --- a/algebra-laws/shared/src/test/scala/algebra/laws/SimpleDeMorgan.scala +++ b/algebra-laws/shared/src/test/scala/algebra/laws/SimpleDeMorgan.scala @@ -28,9 +28,8 @@ import org.scalacheck.Arbitrary import org.scalacheck.Gen.oneOf /** - * The simplest De Morgan algebra that is not already a Boolean algebra. - * It is the standard three valued logic. - * Taken from https://en.wikipedia.org/wiki/De_Morgan_algebra#Kleene_algebra + * The simplest De Morgan algebra that is not already a Boolean algebra. It is the standard three valued logic. Taken + * from https://en.wikipedia.org/wiki/De_Morgan_algebra#Kleene_algebra */ sealed trait SimpleDeMorgan diff --git a/algebra-laws/shared/src/test/scala/algebra/laws/SimpleHeyting.scala b/algebra-laws/shared/src/test/scala/algebra/laws/SimpleHeyting.scala index c21bf1458c..dc277a5888 100644 --- a/algebra-laws/shared/src/test/scala/algebra/laws/SimpleHeyting.scala +++ b/algebra-laws/shared/src/test/scala/algebra/laws/SimpleHeyting.scala @@ -28,8 +28,8 @@ import org.scalacheck.Arbitrary import org.scalacheck.Gen.oneOf /** - * The simplest Heyting algebra that is not already a Boolean algebra. - * Taken from https://en.wikipedia.org/wiki/Heyting_algebra#Examples + * The simplest Heyting algebra that is not already a Boolean algebra. Taken from + * https://en.wikipedia.org/wiki/Heyting_algebra#Examples */ sealed trait SimpleHeyting diff --git a/alleycats-core/src/main/scala/alleycats/ReferentialEq.scala b/alleycats-core/src/main/scala/alleycats/ReferentialEq.scala index 4dc9065c45..289096fc29 100644 --- a/alleycats-core/src/main/scala/alleycats/ReferentialEq.scala +++ b/alleycats-core/src/main/scala/alleycats/ReferentialEq.scala @@ -24,8 +24,7 @@ package alleycats import cats.Eq /** - * An `Eq[A]` that delegates to referential equality (`eq`). - * Note that it is not referentially transparent! + * An `Eq[A]` that delegates to referential equality (`eq`). Note that it is not referentially transparent! */ trait ReferentialEq[A <: AnyRef] extends Eq[A] { def eqv(x: A, y: A): Boolean = x eq y diff --git a/alleycats-core/src/main/scala/alleycats/SystemIdentityHash.scala b/alleycats-core/src/main/scala/alleycats/SystemIdentityHash.scala index 10504f1398..6815e6dbc0 100644 --- a/alleycats-core/src/main/scala/alleycats/SystemIdentityHash.scala +++ b/alleycats-core/src/main/scala/alleycats/SystemIdentityHash.scala @@ -24,8 +24,8 @@ package alleycats import cats.Hash /** - * A `Hash[A]` that delegates to identity hashcode (`System.identityHashCode`). - * It implements `Eq[A]` via referential equality (`eq`) that it is not referentially transparent! + * A `Hash[A]` that delegates to identity hashcode (`System.identityHashCode`). It implements `Eq[A]` via referential + * equality (`eq`) that it is not referentially transparent! */ trait SystemIdentityHash[A <: AnyRef] extends ReferentialEq[A] with Hash[A] { override def hash(a: A): Int = java.lang.System.identityHashCode(a) diff --git a/alleycats-core/src/test/scala/alleycats/SyntaxSuite.scala b/alleycats-core/src/test/scala/alleycats/SyntaxSuite.scala index 394d041f30..88a828c607 100644 --- a/alleycats-core/src/test/scala/alleycats/SyntaxSuite.scala +++ b/alleycats-core/src/test/scala/alleycats/SyntaxSuite.scala @@ -29,18 +29,14 @@ import scala.collection.immutable.SortedMap /** * Test that our syntax implicits are working. * - * Each method should correspond to one type class worth of syntax. - * Ideally, we should be testing every operator or method that we - * expect to add to generic parameters. This file is a safeguard - * against accidentally breaking (or removing) syntax which was - * otherwise untested. + * Each method should correspond to one type class worth of syntax. Ideally, we should be testing every operator or + * method that we expect to add to generic parameters. This file is a safeguard against accidentally breaking (or + * removing) syntax which was otherwise untested. * - * The strategy here is to create "mock" values of particular types, - * and then ensure that the syntax we want is available. We never plan - * to run any of these methods, so we don't need real values. All - * values in the methods should be generic -- we rely on parametricity - * to guarantee that the syntax will be available for any type with - * the proper type class instance(s). + * The strategy here is to create "mock" values of particular types, and then ensure that the syntax we want is + * available. We never plan to run any of these methods, so we don't need real values. All values in the methods should + * be generic -- we rely on parametricity to guarantee that the syntax will be available for any type with the proper + * type class instance(s). * * None of these tests should ever run, or do any runtime checks. */ diff --git a/alleycats-laws/shared/src/test/scala/alleycats/tests/AlleycatsSuite.scala b/alleycats-laws/shared/src/test/scala/alleycats/tests/AlleycatsSuite.scala index f99456bead..daded0a851 100644 --- a/alleycats-laws/shared/src/test/scala/alleycats/tests/AlleycatsSuite.scala +++ b/alleycats-laws/shared/src/test/scala/alleycats/tests/AlleycatsSuite.scala @@ -28,8 +28,7 @@ import org.scalacheck.{Arbitrary, Gen} import org.scalacheck.Test.Parameters /** - * An opinionated stack of traits to improve consistency and reduce - * boilerplate in Alleycats tests. Derived from Cats. + * An opinionated stack of traits to improve consistency and reduce boilerplate in Alleycats tests. Derived from Cats. */ trait AlleycatsSuite extends munit.DisciplineSuite with TestSettings with TestInstances with MapInstances { implicit override def scalaCheckTestParameters: Parameters = diff --git a/bench/src/main/scala/cats/bench/FoldBench.scala b/bench/src/main/scala/cats/bench/FoldBench.scala index d9ea572b98..599aa753b9 100644 --- a/bench/src/main/scala/cats/bench/FoldBench.scala +++ b/bench/src/main/scala/cats/bench/FoldBench.scala @@ -36,12 +36,16 @@ class FoldBench { val charsVector: Vector[String] = chars.toVector val combineStringsSome: (String, String) => Option[String] = (s1, s2) => Some(s1 + s2) - /** Benchmark fold of Foldable[List] */ + /** + * Benchmark fold of Foldable[List] + */ @Benchmark def fold(): String = Foldable[List].fold(chars) - /** Benchmark fold using traverse with Const */ + /** + * Benchmark fold using traverse with Const + */ @Benchmark def traverseConst(): String = Traverse[List].traverse[Const[String, *], String, String](chars)(Const(_)).getConst diff --git a/bench/src/main/scala/cats/bench/ParTraverseBench.scala b/bench/src/main/scala/cats/bench/ParTraverseBench.scala index 98d63a2ec8..0a146bc1e4 100644 --- a/bench/src/main/scala/cats/bench/ParTraverseBench.scala +++ b/bench/src/main/scala/cats/bench/ParTraverseBench.scala @@ -32,11 +32,12 @@ import org.openjdk.jmh.annotations.{Benchmark, Scope, State} * * bench/jmh:run -i 10 -wi 10 -f 5 -t 1 cats.bench.ParTraverseBench * - * Benchmark Mode Cnt Score Error Units - * ParTraverseBench.eitherParBitraversePointfree thrpt 50 20201469.796 ± 143402.778 ops/s - * ParTraverseBench.eitherParBitraversePointfull thrpt 50 24742265.071 ± 133253.733 ops/s - * ParTraverseBench.eitherParTraversePointfree thrpt 50 1150877.660 ± 10162.432 ops/s - * ParTraverseBench.eitherParTraversePointfull thrpt 50 1221809.128 ± 9997.474 ops/s + * | Benchmark | Mode | Cnt | Score | Error | Units | + * |:----------------------------------------------|:------|:----|:-------------|:-------------|:------| + * | ParTraverseBench.eitherParBitraversePointfree | thrpt | 50 | 20201469.796 | ± 143402.778 | ops/s | + * | ParTraverseBench.eitherParBitraversePointfull | thrpt | 50 | 24742265.071 | ± 133253.733 | ops/s | + * | ParTraverseBench.eitherParTraversePointfree | thrpt | 50 | 1150877.660 | ± 10162.432 | ops/s | + * | ParTraverseBench.eitherParTraversePointfull | thrpt | 50 | 1221809.128 | ± 9997.474 | ops/s | */ @State(Scope.Benchmark) class ParTraverseBench { diff --git a/bench/src/main/scala/cats/bench/StateTBench.scala b/bench/src/main/scala/cats/bench/StateTBench.scala index de8c545706..82d18a6c12 100644 --- a/bench/src/main/scala/cats/bench/StateTBench.scala +++ b/bench/src/main/scala/cats/bench/StateTBench.scala @@ -28,7 +28,7 @@ import org.openjdk.jmh.annotations.* /** * To run: * - * bench/jmh:run -i 10 -wi 10 -f 2 -t 1 cats.bench.StateTBench + * bench/jmh:run -i 10 -wi 10 -f 2 -t 1 cats.bench.StateTBench */ @State(Scope.Thread) @BenchmarkMode(Array(Mode.Throughput)) diff --git a/core/src/main/scala-2.12/cats/compat/ChainCompat.scala b/core/src/main/scala-2.12/cats/compat/ChainCompat.scala index b4c29c7cfb..0bcde20ca2 100644 --- a/core/src/main/scala-2.12/cats/compat/ChainCompat.scala +++ b/core/src/main/scala-2.12/cats/compat/ChainCompat.scala @@ -24,8 +24,8 @@ package cats.data private[data] trait ChainCompat[+A] { _: Chain[A] => /** - * The number of elements in this chain, if it can be cheaply computed, -1 otherwise. - * Cheaply usually means: Not requiring a collection traversal. + * The number of elements in this chain, if it can be cheaply computed, -1 otherwise. Cheaply usually means: Not + * requiring a collection traversal. */ final def knownSize: Long = this match { diff --git a/core/src/main/scala-2.12/cats/evidence/AsSupport.scala b/core/src/main/scala-2.12/cats/evidence/AsSupport.scala index 6e3862f646..4e2dd8dbbd 100644 --- a/core/src/main/scala-2.12/cats/evidence/AsSupport.scala +++ b/core/src/main/scala-2.12/cats/evidence/AsSupport.scala @@ -24,9 +24,8 @@ package cats.evidence private[evidence] trait AsSupport { /** - * In 2.13 there is a method on ev that makes this safe. - * But lack of this method does not make the cast unsafe - * it just makes it not provable without the cast. + * In 2.13 there is a method on ev that makes this safe. But lack of this method does not make the cast unsafe it just + * makes it not provable without the cast. */ @inline implicit def asFromPredef[A, B](implicit ev: A <:< B): A As B = As.refl[A].asInstanceOf[A As B] diff --git a/core/src/main/scala-2.12/cats/evidence/IsSupport.scala b/core/src/main/scala-2.12/cats/evidence/IsSupport.scala index 573a9f85c3..a03f3d36b7 100644 --- a/core/src/main/scala-2.12/cats/evidence/IsSupport.scala +++ b/core/src/main/scala-2.12/cats/evidence/IsSupport.scala @@ -24,9 +24,8 @@ package cats.evidence private[evidence] trait IsSupport { /** - * In 2.13 there is a method on ev that makes this safe. - * But lack of this method does not make the cast unsafe - * it just makes it not provable without the cast. + * In 2.13 there is a method on ev that makes this safe. But lack of this method does not make the cast unsafe it just + * makes it not provable without the cast. */ @inline implicit def isFromPredef[A, B](implicit ev: A =:= B): A Is B = Is.refl[A].asInstanceOf[A Is B] diff --git a/core/src/main/scala-2.12/cats/instances/package.scala b/core/src/main/scala-2.12/cats/instances/package.scala index 35b41d9b0e..d181e9ee4c 100644 --- a/core/src/main/scala-2.12/cats/instances/package.scala +++ b/core/src/main/scala-2.12/cats/instances/package.scala @@ -42,12 +42,13 @@ package object instances { /** * @deprecated - * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone - * (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). - * We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]]. - * However, at this time there are no plans to remove these instances from Cats. + * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone (particularly the semantics of + * [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). We recommend using + * [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of + * [[scala.concurrent.Future Future]]. However, at this time there are no plans to remove these instances from Cats. * - * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] + * @see + * [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] */ object future extends FutureInstances diff --git a/core/src/main/scala-2.13+/cats/data/ChainCompat.scala b/core/src/main/scala-2.13+/cats/data/ChainCompat.scala index 8541f1356e..635c9a8df8 100644 --- a/core/src/main/scala-2.13+/cats/data/ChainCompat.scala +++ b/core/src/main/scala-2.13+/cats/data/ChainCompat.scala @@ -25,8 +25,8 @@ package data private[data] trait ChainCompat[+A] { self: Chain[A] => /** - * The number of elements in this chain, if it can be cheaply computed, -1 otherwise. - * Cheaply usually means: Not requiring a collection traversal. + * The number of elements in this chain, if it can be cheaply computed, -1 otherwise. Cheaply usually means: Not + * requiring a collection traversal. */ final def knownSize: Long = this match { diff --git a/core/src/main/scala-2.13+/cats/data/NonEmptyLazyList.scala b/core/src/main/scala-2.13+/cats/data/NonEmptyLazyList.scala index 478b338651..a442b725f9 100644 --- a/core/src/main/scala-2.13+/cats/data/NonEmptyLazyList.scala +++ b/core/src/main/scala-2.13+/cats/data/NonEmptyLazyList.scala @@ -240,15 +240,15 @@ class NonEmptyLazyListOps[A](private val value: NonEmptyLazyList[A]) toLazyList.collect(pf) /** - * Finds the first element of this `NonEmptyLazyList` for which the given partial - * function is defined, and applies the partial function to it. + * Finds the first element of this `NonEmptyLazyList` for which the given partial function is defined, and applies the + * partial function to it. */ @deprecated("Use collectFirst", "2.2.0-M1") final def collectLazyList[B](pf: PartialFunction[A, B]): Option[B] = collectFirst(pf) /** - * Finds the first element of this `NonEmptyLazyList` for which the given partial - * function is defined, and applies the partial function to it. + * Finds the first element of this `NonEmptyLazyList` for which the given partial function is defined, and applies the + * partial function to it. */ final def collectFirst[B](pf: PartialFunction[A, B]): Option[B] = toLazyList.collectFirst(pf) @@ -281,8 +281,8 @@ class NonEmptyLazyListOps[A](private val value: NonEmptyLazyList[A]) toLazyList.reduceLeft(f) /** - * Apply `f` to the "initial element" of this LazyList and lazily combine it - * with every other value using the given function `g`. + * Apply `f` to the "initial element" of this LazyList and lazily combine it with every other value using the given + * function `g`. */ final def reduceLeftTo[B](f: A => B)(g: (B, A) => B): B = { val iter = toLazyList.iterator @@ -298,8 +298,8 @@ class NonEmptyLazyListOps[A](private val value: NonEmptyLazyList[A]) toLazyList.reduceRight(f) /** - * Apply `f` to the "initial element" of this NonEmptyLazyList and - * lazily combine it with every other value using the given function `g`. + * Apply `f` to the "initial element" of this NonEmptyLazyList and lazily combine it with every other value using the + * given function `g`. */ final def reduceRightTo[B](f: A => B)(g: (A, B) => B): B = { val iter = toLazyList.reverseIterator @@ -392,8 +392,8 @@ class NonEmptyLazyListOps[A](private val value: NonEmptyLazyList[A]) create(toLazyList.sorted(AA.toOrdering)) /** - * Groups elements inside this `NonEmptyLazyList` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptyLazyList` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -425,8 +425,8 @@ class NonEmptyLazyListOps[A](private val value: NonEmptyLazyList[A]) } /** - * Groups elements inside this `NonEmptyLazyList` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptyLazyList` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import cats.data.{NonEmptyLazyList, NonEmptyMap} diff --git a/core/src/main/scala-2.13+/cats/instances/package.scala b/core/src/main/scala-2.13+/cats/instances/package.scala index 7b0cfaac02..8fca0f2d11 100644 --- a/core/src/main/scala-2.13+/cats/instances/package.scala +++ b/core/src/main/scala-2.13+/cats/instances/package.scala @@ -43,12 +43,13 @@ package object instances { /** * @deprecated - * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone - * (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). - * We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]]. - * However, at this time there are no plans to remove these instances from Cats. + * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone (particularly the semantics of + * [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). We recommend using + * [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of + * [[scala.concurrent.Future Future]]. However, at this time there are no plans to remove these instances from Cats. * - * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] + * @see + * [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] */ object future extends FutureInstances diff --git a/core/src/main/scala-2/cats/arrow/FunctionKMacros.scala b/core/src/main/scala-2/cats/arrow/FunctionKMacros.scala index 764bb8fec7..f3207895a7 100644 --- a/core/src/main/scala-2/cats/arrow/FunctionKMacros.scala +++ b/core/src/main/scala-2/cats/arrow/FunctionKMacros.scala @@ -34,8 +34,7 @@ private[arrow] class FunctionKMacroMethods extends FunctionKLift { * val lifted: FunctionK[List, Option] = FunctionK.lift(headOption) * }}} * - * Note: This method has a macro implementation that returns a new - * `FunctionK` instance as follows: + * Note: This method has a macro implementation that returns a new `FunctionK` instance as follows: * * {{{ * new FunctionK[F, G] { diff --git a/core/src/main/scala/cats/Align.scala b/core/src/main/scala/cats/Align.scala index 0b871930cc..bbff2aa485 100644 --- a/core/src/main/scala/cats/Align.scala +++ b/core/src/main/scala/cats/Align.scala @@ -25,8 +25,8 @@ import cats.data.Ior import scala.collection.immutable.{Seq, SortedMap} /** - * `Align` supports zipping together structures with different shapes, - * holding the results from either or both structures in an `Ior`. + * `Align` supports zipping together structures with different shapes, holding the results from either or both + * structures in an `Ior`. * * Must obey the laws in cats.laws.AlignLaws */ diff --git a/core/src/main/scala/cats/Alternative.scala b/core/src/main/scala/cats/Alternative.scala index 2cba69e1f3..be18e58888 100644 --- a/core/src/main/scala/cats/Alternative.scala +++ b/core/src/main/scala/cats/Alternative.scala @@ -35,11 +35,9 @@ trait Alternative[F[_]] extends NonEmptyAlternative[F] with MonoidK[F] { self => } /** - * Fold over the inner structure to combine all of the values with - * our combine method inherited from MonoidK. The result is for us - * to accumulate all of the "interesting" values of the inner G, so - * if G is Option, we collect all the Some values, if G is Either, - * we collect all the Right values, etc. + * Fold over the inner structure to combine all of the values with our combine method inherited from MonoidK. The + * result is for us to accumulate all of the "interesting" values of the inner G, so if G is Option, we collect all + * the Some values, if G is Either, we collect all the Right values, etc. * * Example: * {{{ @@ -79,9 +77,9 @@ trait Alternative[F[_]] extends NonEmptyAlternative[F] with MonoidK[F] { self => /** * Separate the inner foldable values into the "lefts" and "rights". * - * A variant of [[[separate[G[_,_],A,B](fgab:F[G[A,B]])(implicitFM:cats\.FlatMap[F]* separate]]] - * that is specialized for Fs that have Foldable instances which allows for a single-pass implementation - * (as opposed to {{{separate}}} which is 2-pass). + * A variant of [[[separate[G[_,_],A,B](fgab:F[G[A,B]])(implicitFM:cats\.FlatMap[F]* separate]]] that is specialized + * for Fs that have Foldable instances which allows for a single-pass implementation (as opposed to {{{separate}}} + * which is 2-pass). * * Example: * {{{ diff --git a/core/src/main/scala/cats/Applicative.scala b/core/src/main/scala/cats/Applicative.scala index a85e720e15..20a3e69f8c 100644 --- a/core/src/main/scala/cats/Applicative.scala +++ b/core/src/main/scala/cats/Applicative.scala @@ -31,8 +31,10 @@ import scala.annotation.tailrec * * Allows application of a function in an Applicative context to a value in an Applicative context * - * See: [[https://www.cs.ox.ac.uk/jeremy.gibbons/publications/iterator.pdf The Essence of the Iterator Pattern]] - * Also: [[http://staff.city.ac.uk/~ross/papers/Applicative.pdf Applicative programming with effects]] + * @see + * [[https://www.cs.ox.ac.uk/jeremy.gibbons/publications/iterator.pdf The Essence of the Iterator Pattern]] + * @see + * [[http://staff.city.ac.uk/~ross/papers/Applicative.pdf Applicative programming with effects]] * * Must obey the laws defined in cats.laws.ApplicativeLaws. */ @@ -54,8 +56,7 @@ trait Applicative[F[_]] extends Apply[F] with InvariantMonoidal[F] { self => /** * Returns an `F[Unit]` value, equivalent with `pure(())`. * - * A useful shorthand, also allowing implementations to optimize the - * returned reference (e.g. it can be a `val`). + * A useful shorthand, also allowing implementations to optimize the returned reference (e.g. it can be a `val`). * * Example: * {{{ @@ -145,8 +146,7 @@ trait Applicative[F[_]] extends Apply[F] with InvariantMonoidal[F] { self => } /** - * Compose an `Applicative[F]` and an `Applicative[G]` into an - * `Applicative[λ[α => F[G[α]]]]`. + * Compose an `Applicative[F]` and an `Applicative[G]` into an `Applicative[λ[α => F[G[α]]]]`. * * Example: * {{{ @@ -168,8 +168,7 @@ trait Applicative[F[_]] extends Apply[F] with InvariantMonoidal[F] { self => } /** - * Compose an `Applicative[F]` and a `ContravariantMonoidal[G]` into a - * `ContravariantMonoidal[λ[α => F[G[α]]]]`. + * Compose an `Applicative[F]` and a `ContravariantMonoidal[G]` into a `ContravariantMonoidal[λ[α => F[G[α]]]]`. * * Example: * {{{ @@ -216,8 +215,7 @@ trait Applicative[F[_]] extends Apply[F] with InvariantMonoidal[F] { self => } /** - * Returns the given argument (mapped to Unit) if `cond` is `false`, - * otherwise, unit lifted into F. + * Returns the given argument (mapped to Unit) if `cond` is `false`, otherwise, unit lifted into F. * * Example: * {{{ @@ -240,8 +238,7 @@ trait Applicative[F[_]] extends Apply[F] with InvariantMonoidal[F] { self => if (cond) unit else void(f) /** - * Returns the given argument (mapped to Unit) if `cond` is `true`, otherwise, - * unit lifted into F. + * Returns the given argument (mapped to Unit) if `cond` is `true`, otherwise, unit lifted into F. * * Example: * {{{ @@ -270,8 +267,7 @@ object Applicative { new ApplicativeMonoid[F, A](f, monoid) /** - * Creates an applicative functor for `F`, holding domain fixed and combining - * over the codomain. + * Creates an applicative functor for `F`, holding domain fixed and combining over the codomain. * * Example: * {{{ @@ -288,8 +284,7 @@ object Applicative { new ArrowApplicative[F, A](F) /** - * Creates a CoflatMap for an Applicative `F`. - * Cannot be implicit in 1.0 for Binary Compatibility Reasons + * Creates a CoflatMap for an Applicative `F`. Cannot be implicit in 1.0 for Binary Compatibility Reasons * * Example: * {{{ diff --git a/core/src/main/scala/cats/ApplicativeError.scala b/core/src/main/scala/cats/ApplicativeError.scala index 7582fca4ed..c01329b115 100644 --- a/core/src/main/scala/cats/ApplicativeError.scala +++ b/core/src/main/scala/cats/ApplicativeError.scala @@ -62,11 +62,12 @@ trait ApplicativeError[F[_], E] extends Applicative[F] { /** * Returns `raiseError` when the `cond` is true, otherwise `F.unit` * - * @example {{{ - * val tooMany = 5 - * val x: Int = ??? - * F.raiseWhen(x >= tooMany)(new IllegalArgumentException("Too many")) - * }}} + * @example + * {{{ + * val tooMany = 5 + * val x: Int = ??? + * F.raiseWhen(x >= tooMany)(new IllegalArgumentException("Too many")) + * }}} */ def raiseWhen(cond: Boolean)(e: => E): F[Unit] = whenA(cond)(raiseError(e)) @@ -74,41 +75,42 @@ trait ApplicativeError[F[_], E] extends Applicative[F] { /** * Returns `raiseError` when `cond` is false, otherwise `F.unit` * - * @example {{{ - * val tooMany = 5 - * val x: Int = ??? - * F.raiseUnless(x < tooMany)(new IllegalArgumentException("Too many")) - * }}} + * @example + * {{{ + * val tooMany = 5 + * val x: Int = ??? + * F.raiseUnless(x < tooMany)(new IllegalArgumentException("Too many")) + * }}} */ def raiseUnless(cond: Boolean)(e: => E): F[Unit] = unlessA(cond)(raiseError(e)) /** - * Handle any error, potentially recovering from it, by mapping it to an - * `F[A]` value. + * Handle any error, potentially recovering from it, by mapping it to an `F[A]` value. * - * @see [[handleError]] to handle any error by simply mapping it to an `A` - * value instead of an `F[A]`. + * @see + * [[handleError]] to handle any error by simply mapping it to an `A` value instead of an `F[A]`. * - * @see [[recoverWith]] to recover from only certain errors. + * @see + * [[recoverWith]] to recover from only certain errors. */ def handleErrorWith[A](fa: F[A])(f: E => F[A]): F[A] /** * Handle any error, by mapping it to an `A` value. * - * @see [[handleErrorWith]] to map to an `F[A]` value instead of simply an - * `A` value. + * @see + * [[handleErrorWith]] to map to an `F[A]` value instead of simply an `A` value. * - * @see [[recover]] to only recover from certain errors. + * @see + * [[recover]] to only recover from certain errors. */ def handleError[A](fa: F[A])(f: E => A): F[A] = handleErrorWith(fa)(f.andThen(pure)) /** * Void any error, by mapping it to `Unit`. * - * This is useful when errors are reported via a side-channel but not directly handled. - * For example in Cats Effect: + * This is useful when errors are reported via a side-channel but not directly handled. For example in Cats Effect: * * {{{ * IO.deferred[OutcomeIO[A]].flatMap { oc => @@ -117,11 +119,13 @@ trait ApplicativeError[F[_], E] extends Applicative[F] { * } * }}} * - * Without the `.voidError`, the Cats Effect runtime would consider an error in `ioa` to be - * unhandled and elevate it to [[scala.concurrent.ExecutionContext.reportFailure ExecutionContext#reportFailure]]. + * Without the `.voidError`, the Cats Effect runtime would consider an error in `ioa` to be unhandled and elevate it + * to [[scala.concurrent.ExecutionContext.reportFailure ExecutionContext#reportFailure]]. * - * @see [[handleError]] to map to an `A` value instead of `Unit`. - * @see [[https://github.com/typelevel/cats-effect/issues/3152 cats-effect#3152]] + * @see + * [[handleError]] to map to an `A` value instead of `Unit`. + * @see + * [[https://github.com/typelevel/cats-effect/issues/3152 cats-effect#3152]] */ def voidError(fu: F[Unit]): F[Unit] = handleError(fu)(Function.const(())) @@ -138,8 +142,7 @@ trait ApplicativeError[F[_], E] extends Applicative[F] { )(e => pure(Left(e))) /** - * Similar to [[attempt]], but wraps the result in a [[cats.data.EitherT]] for - * convenience. + * Similar to [[attempt]], but wraps the result in a [[cats.data.EitherT]] for convenience. */ def attemptT[A](fa: F[A]): EitherT[F, E, A] = EitherT(attempt(fa)) @@ -152,10 +155,11 @@ trait ApplicativeError[F[_], E] extends Applicative[F] { /** * Recover from certain errors by mapping them to an `A` value. * - * @see [[handleError]] to handle any/all errors. + * @see + * [[handleError]] to handle any/all errors. * - * @see [[recoverWith]] to recover from certain errors by mapping them to - * `F[A]` values. + * @see + * [[recoverWith]] to recover from certain errors by mapping them to `F[A]` values. */ def recover[A](fa: F[A])(pf: PartialFunction[E, A]): F[A] = handleErrorWith(fa)(e => pf.andThen(pure(_)).applyOrElse(e, raiseError[A](_))) @@ -163,17 +167,18 @@ trait ApplicativeError[F[_], E] extends Applicative[F] { /** * Recover from certain errors by mapping them to an `F[A]` value. * - * @see [[handleErrorWith]] to handle any/all errors. + * @see + * [[handleErrorWith]] to handle any/all errors. * - * @see [[recover]] to recover from certain errors by mapping them to `A` - * values. + * @see + * [[recover]] to recover from certain errors by mapping them to `A` values. */ def recoverWith[A](fa: F[A])(pf: PartialFunction[E, F[A]]): F[A] = handleErrorWith(fa)(e => pf.applyOrElse(e, raiseError)) /** - * Transform certain errors using `pf` and rethrow them. - * Non matching errors and successful values are not affected by this function. + * Transform certain errors using `pf` and rethrow them. Non matching errors and successful values are not affected by + * this function. * * Example: * {{{ @@ -191,20 +196,18 @@ trait ApplicativeError[F[_], E] extends Applicative[F] { * res2: Either[String,Int] = Right(1) * }}} * - * The same function is available in `ApplicativeErrorOps` as `adaptErr` - it cannot have the same - * name because this would result in ambiguous implicits due to `adaptError` - * having originally been included in the `MonadError` API and syntax. + * The same function is available in `ApplicativeErrorOps` as `adaptErr` - it cannot have the same name because this + * would result in ambiguous implicits due to `adaptError` having originally been included in the `MonadError` API and + * syntax. */ def adaptError[A](fa: F[A])(pf: PartialFunction[E, E]): F[A] = recoverWith(fa)(pf.andThen(raiseError[A] _)) /** - * Returns a new value that transforms the result of the source, - * given the `recover` or `map` functions, which get executed depending - * on whether the result is successful or if it ends in error. + * Returns a new value that transforms the result of the source, given the `recover` or `map` functions, which get + * executed depending on whether the result is successful or if it ends in error. * - * This is an optimization on usage of [[attempt]] and [[map]], - * this equivalence being available: + * This is an optimization on usage of [[attempt]] and [[map]], this equivalence being available: * * {{{ * fa.redeem(fe, fs) <-> fa.attempt.map(_.fold(fe, fs)) @@ -216,25 +219,24 @@ trait ApplicativeError[F[_], E] extends Applicative[F] { * fa.redeem(fe, id) <-> fa.handleError(fe) * }}} * - * Implementations are free to override it in order to optimize - * error recovery. + * Implementations are free to override it in order to optimize error recovery. * - * @see [[MonadError.redeemWith]], [[attempt]] and [[handleError]] + * @see + * [[MonadError.redeemWith]], [[attempt]] and [[handleError]] * - * @param fa is the source whose result is going to get transformed - * @param recover is the function that gets called to recover the source - * in case of error + * @param fa + * is the source whose result is going to get transformed + * @param recover + * is the function that gets called to recover the source in case of error */ def redeem[A, B](fa: F[A])(recover: E => B, f: A => B): F[B] = handleError(map(fa)(f))(recover) /** - * Execute a callback on certain errors, then rethrow them. - * Any non matching error is rethrown as well. + * Execute a callback on certain errors, then rethrow them. Any non matching error is rethrown as well. * - * In the following example, only one of the errors is logged, - * but they are both rethrown, to be possibly handled by another - * layer of the program: + * In the following example, only one of the errors is logged, but they are both rethrown, to be possibly handled by + * another layer of the program: * * {{{ * scala> import cats._, data._, implicits._ @@ -262,8 +264,7 @@ trait ApplicativeError[F[_], E] extends Applicative[F] { handleErrorWith(fa)(e => pf.andThen(map2(_, raiseError[A](e))((_, b) => b)).applyOrElse(e, raiseError)) /** - * Often E is Throwable. Here we try to call pure or catch - * and raise. + * Often E is Throwable. Here we try to call pure or catch and raise. */ def catchNonFatal[A](a: => A)(implicit ev: Throwable <:< E): F[A] = try pure(a) @@ -272,8 +273,7 @@ trait ApplicativeError[F[_], E] extends Applicative[F] { } /** - * Often E is Throwable. Here we try to call pure or catch - * and raise + * Often E is Throwable. Here we try to call pure or catch and raise */ def catchNonFatalEval[A](a: Eval[A])(implicit ev: Throwable <:< E): F[A] = try pure(a.value) diff --git a/core/src/main/scala/cats/Apply.scala b/core/src/main/scala/cats/Apply.scala index f153632841..4e04c56f0c 100644 --- a/core/src/main/scala/cats/Apply.scala +++ b/core/src/main/scala/cats/Apply.scala @@ -31,8 +31,7 @@ import cats.data.Ior trait Apply[F[_]] extends Functor[F] with InvariantSemigroupal[F] with ApplyArityFunctions[F] { self => /** - * Given a value and a function in the Apply context, applies the - * function to the value. + * Given a value and a function in the Apply context, applies the function to the value. * * Example: * {{{ @@ -61,7 +60,8 @@ trait Apply[F[_]] extends Functor[F] with InvariantSemigroupal[F] with ApplyArit /** * Compose two actions, discarding any value produced by the first. * - * @see [[productL]] to discard the value of the second instead. + * @see + * [[productL]] to discard the value of the second instead. * * Example: * {{{ @@ -95,7 +95,8 @@ trait Apply[F[_]] extends Functor[F] with InvariantSemigroupal[F] with ApplyArit /** * Compose two actions, discarding any value produced by the second. * - * @see [[productR]] to discard the value of the first instead. + * @see + * [[productR]] to discard the value of the first instead. * * Example: * {{{ @@ -198,16 +199,14 @@ trait Apply[F[_]] extends Functor[F] with InvariantSemigroupal[F] with ApplyArit map(product(fa, fb))(f.tupled) /** - * Similar to [[map2]] but uses [[Eval]] to allow for laziness in the `F[B]` - * argument. This can allow for "short-circuiting" of computations. + * Similar to [[map2]] but uses [[Eval]] to allow for laziness in the `F[B]` argument. This can allow for + * "short-circuiting" of computations. * - * NOTE: the default implementation of `map2Eval` does not short-circuit - * computations. For data structures that can benefit from laziness, [[Apply]] - * instances should override this method. + * NOTE: the default implementation of `map2Eval` does not short-circuit computations. For data structures that can + * benefit from laziness, [[Apply]] instances should override this method. * - * In the following example, `x.map2(bomb)(_ + _)` would result in an error, - * but `map2Eval` "short-circuits" the computation. `x` is `None` and thus the - * result of `bomb` doesn't even need to be evaluated in order to determine + * In the following example, `x.map2(bomb)(_ + _)` would result in an error, but `map2Eval` "short-circuits" the + * computation. `x` is `None` and thus the result of `bomb` doesn't even need to be evaluated in order to determine * that the result of `map2Eval` should be `None`. * * {{{ @@ -252,10 +251,9 @@ object Apply { abstract private[cats] class AbstractApply[F[_]] extends Apply[F] /** - * This semigroup uses a product operation to combine `F`s. - * If the `Apply[F].product` results in larger `F` (i.e. when `F` is a `List`), - * accumulative usage of this instance, such as `combineAll`, will result in - * `F`s with exponentially increasing sizes. + * This semigroup uses a product operation to combine `F`s. If the `Apply[F].product` results in larger `F` (i.e. when + * `F` is a `List`), accumulative usage of this instance, such as `combineAll`, will result in `F`s with exponentially + * increasing sizes. */ def semigroup[F[_], A](implicit f: Apply[F], sg: Semigroup[A]): Semigroup[F[A]] = new ApplySemigroup[F, A](f, sg) diff --git a/core/src/main/scala/cats/Bifoldable.scala b/core/src/main/scala/cats/Bifoldable.scala index 9b815ec438..c3a6c223a6 100644 --- a/core/src/main/scala/cats/Bifoldable.scala +++ b/core/src/main/scala/cats/Bifoldable.scala @@ -49,16 +49,14 @@ trait Bifoldable[F[_, _]] extends Serializable { self => def bifoldLeft[A, B, C](fab: F[A, B], c: C)(f: (C, A) => C, g: (C, B) => C): C /** - * Collapse the structure with a right-associative function - * Right associative lazy bifold on `F` using the folding function 'f' and 'g'. + * Collapse the structure with a right-associative function Right associative lazy bifold on `F` using the folding + * function 'f' and 'g'. * - * This method evaluates `c` lazily (in some cases it will not be - * needed), and returns a lazy value. We are using `(_, Eval[C]) => - * Eval[C]` to support laziness in a stack-safe way. Chained - * computation should be performed via .map and .flatMap. + * This method evaluates `c` lazily (in some cases it will not be needed), and returns a lazy value. We are using `(_, + * Eval[C]) => Eval[C]` to support laziness in a stack-safe way. Chained computation should be performed via .map and + * .flatMap. * - * For more detailed information about how this method works see the - * documentation for `Eval[_]`. + * For more detailed information about how this method works see the documentation for `Eval[_]`. * * Example: * {{{ diff --git a/core/src/main/scala/cats/Bifunctor.scala b/core/src/main/scala/cats/Bifunctor.scala index 58915b08bf..12c335d6f9 100644 --- a/core/src/main/scala/cats/Bifunctor.scala +++ b/core/src/main/scala/cats/Bifunctor.scala @@ -22,14 +22,12 @@ package cats /** - * A type class of types which give rise to two independent, covariant - * functors. + * A type class of types which give rise to two independent, covariant functors. */ trait Bifunctor[F[_, _]] extends Serializable { self => /** - * The quintessential method of the Bifunctor trait, it applies a - * function to each "side" of the bifunctor. + * The quintessential method of the Bifunctor trait, it applies a function to each "side" of the bifunctor. * * Example: * {{{ @@ -65,6 +63,7 @@ trait Bifunctor[F[_, _]] extends Serializable { self => /** * Widens A into a supertype AA. + * * Example: * {{{ * scala> import cats.syntax.all._ @@ -78,13 +77,13 @@ trait Bifunctor[F[_, _]] extends Serializable { self => /** * Lift left into F using Applicative. - * * Example: + * + * Example: * {{{ * scala> import cats.syntax.all._ * scala> val x0: Either[String, Int] = Either.left("foo") * scala> val x1: Either[List[String], Int] = x0.leftLiftTo[List] * }}} - * */ def leftLiftTo[A, B, C[_]](fab: F[A, B])(implicit C: Applicative[C]): F[C[A], B] = leftMap[A, B, C[A]](fab)(C.pure[A]) diff --git a/core/src/main/scala/cats/Bitraverse.scala b/core/src/main/scala/cats/Bitraverse.scala index 91e02e9117..b05c2c03aa 100644 --- a/core/src/main/scala/cats/Bitraverse.scala +++ b/core/src/main/scala/cats/Bitraverse.scala @@ -84,11 +84,11 @@ trait Bitraverse[F[_, _]] extends Bifoldable[F] with Bifunctor[F] { self => bitraverse[Id, A, B, C, D](fab)(f, g) /** - * Traverse over the left side of the structure. - * For the right side, use the standard `traverse` from [[cats.Traverse]]. + * Traverse over the left side of the structure. For the right side, use the standard `traverse` from + * [[cats.Traverse]]. * - * Example: - * {{{ + * Example: + * {{{ * scala> import cats.syntax.all._ * * scala> val intAndString: (Int, String) = (7, "test") @@ -98,15 +98,14 @@ trait Bitraverse[F[_, _]] extends Bifoldable[F] with Bifunctor[F] { self => * * scala> Bitraverse[Tuple2].leftTraverse(intAndString)(i => Option(i).filter(_ < 5)) * res2: Option[(Int, String)] = None - * }}} + * }}} */ def leftTraverse[G[_], A, B, C](fab: F[A, B])(f: A => G[C])(implicit G: Applicative[G]): G[F[C, B]] = bitraverse(fab)(f, G.pure(_)) /** - * Sequence the left side of the structure. - * For the right side, use the standard `sequence` from [[cats.Traverse]]. + * Sequence the left side of the structure. For the right side, use the standard `sequence` from [[cats.Traverse]]. * * Example: * {{{ diff --git a/core/src/main/scala/cats/CoflatMap.scala b/core/src/main/scala/cats/CoflatMap.scala index d6001c4923..3d025a2b4f 100644 --- a/core/src/main/scala/cats/CoflatMap.scala +++ b/core/src/main/scala/cats/CoflatMap.scala @@ -29,8 +29,7 @@ package cats trait CoflatMap[F[_]] extends Functor[F] { /** - * `coflatMap` is the dual of `flatMap` on `FlatMap`. It applies - * a value in a context to a function that takes a value + * `coflatMap` is the dual of `flatMap` on `FlatMap`. It applies a value in a context to a function that takes a value * in a context and returns a normal value. * * Example: @@ -48,8 +47,8 @@ trait CoflatMap[F[_]] extends Functor[F] { def coflatMap[A, B](fa: F[A])(f: F[A] => B): F[B] /** - * `coflatten` is the dual of `flatten` on `FlatMap`. Whereas flatten removes - * a layer of `F`, coflatten adds a layer of `F` + * `coflatten` is the dual of `flatten` on `FlatMap`. Whereas flatten removes a layer of `F`, coflatten adds a layer + * of `F` * * Example: * {{{ diff --git a/core/src/main/scala/cats/CommutativeApplicative.scala b/core/src/main/scala/cats/CommutativeApplicative.scala index 8f8a0dad2e..60f0fb9365 100644 --- a/core/src/main/scala/cats/CommutativeApplicative.scala +++ b/core/src/main/scala/cats/CommutativeApplicative.scala @@ -26,9 +26,8 @@ import cats.kernel.CommutativeMonoid /** * Commutative Applicative. * - * Further than an Applicative, which just allows composition of independent effectful functions, - * in a Commutative Applicative those functions can be composed in any order, which guarantees - * that their effects do not interfere. + * Further than an Applicative, which just allows composition of independent effectful functions, in a Commutative + * Applicative those functions can be composed in any order, which guarantees that their effects do not interfere. * * Must obey the laws defined in cats.laws.CommutativeApplicativeLaws. */ diff --git a/core/src/main/scala/cats/CommutativeApply.scala b/core/src/main/scala/cats/CommutativeApply.scala index aad8735957..9df77e7cbb 100644 --- a/core/src/main/scala/cats/CommutativeApply.scala +++ b/core/src/main/scala/cats/CommutativeApply.scala @@ -26,9 +26,8 @@ import cats.kernel.CommutativeSemigroup /** * Commutative Apply. * - * Further than an Apply, which just allows composition of independent effectful functions, - * in a Commutative Apply those functions can be composed in any order, which guarantees - * that their effects do not interfere. + * Further than an Apply, which just allows composition of independent effectful functions, in a Commutative Apply those + * functions can be composed in any order, which guarantees that their effects do not interfere. * * Must obey the laws defined in cats.laws.CommutativeApplyLaws. */ diff --git a/core/src/main/scala/cats/CommutativeFlatMap.scala b/core/src/main/scala/cats/CommutativeFlatMap.scala index ed6f88f41c..f3438fc3c7 100644 --- a/core/src/main/scala/cats/CommutativeFlatMap.scala +++ b/core/src/main/scala/cats/CommutativeFlatMap.scala @@ -24,9 +24,8 @@ package cats /** * Commutative FlatMap. * - * Further than a FlatMap, which just allows composition of dependent effectful functions, - * in a Commutative FlatMap those functions can be composed in any order, which guarantees - * that their effects do not interfere. + * Further than a FlatMap, which just allows composition of dependent effectful functions, in a Commutative FlatMap + * those functions can be composed in any order, which guarantees that their effects do not interfere. * * Must obey the laws defined in cats.laws.CommutativeFlatMapLaws. */ diff --git a/core/src/main/scala/cats/CommutativeMonad.scala b/core/src/main/scala/cats/CommutativeMonad.scala index a79b73c1bc..ce9c082f12 100644 --- a/core/src/main/scala/cats/CommutativeMonad.scala +++ b/core/src/main/scala/cats/CommutativeMonad.scala @@ -24,9 +24,8 @@ package cats /** * Commutative Monad. * - * Further than a Monad, which just allows composition of dependent effectful functions, - * in a Commutative Monad those functions can be composed in any order, which guarantees - * that their effects do not interfere. + * Further than a Monad, which just allows composition of dependent effectful functions, in a Commutative Monad those + * functions can be composed in any order, which guarantees that their effects do not interfere. * * Must obey the laws defined in cats.laws.CommutativeMonadLaws. */ diff --git a/core/src/main/scala/cats/Comonad.scala b/core/src/main/scala/cats/Comonad.scala index 2db0275332..0b3b86de68 100644 --- a/core/src/main/scala/cats/Comonad.scala +++ b/core/src/main/scala/cats/Comonad.scala @@ -24,16 +24,15 @@ package cats /** * Comonad * - * Comonad is the dual of Monad. Whereas Monads allow for the composition of effectful functions, - * Comonads allow for composition of functions that extract the value from their context. + * Comonad is the dual of Monad. Whereas Monads allow for the composition of effectful functions, Comonads allow for + * composition of functions that extract the value from their context. * * Must obey the laws defined in cats.laws.ComonadLaws. */ trait Comonad[F[_]] extends CoflatMap[F] { /** - * `extract` is the dual of `pure` on Monad (via `Applicative`) - * and extracts the value from its context + * `extract` is the dual of `pure` on Monad (via `Applicative`) and extracts the value from its context * * Example: * {{{ diff --git a/core/src/main/scala/cats/Contravariant.scala b/core/src/main/scala/cats/Contravariant.scala index 1d7213a20e..2e9f2c139e 100644 --- a/core/src/main/scala/cats/Contravariant.scala +++ b/core/src/main/scala/cats/Contravariant.scala @@ -35,8 +35,8 @@ trait Contravariant[F[_]] extends Invariant[F] { self => } /** - * Lifts natural subtyping contravariance of contravariant Functors. - * could be implemented as contramap(identity), but the Functor laws say this is equivalent + * Lifts natural subtyping contravariance of contravariant Functors. could be implemented as contramap(identity), but + * the Functor laws say this is equivalent */ def narrow[A, B <: A](fa: F[A]): F[B] = fa.asInstanceOf[F[B]] diff --git a/core/src/main/scala/cats/ContravariantMonoidal.scala b/core/src/main/scala/cats/ContravariantMonoidal.scala index d534fe34bb..120b9cad4d 100644 --- a/core/src/main/scala/cats/ContravariantMonoidal.scala +++ b/core/src/main/scala/cats/ContravariantMonoidal.scala @@ -22,8 +22,8 @@ package cats /** - * [[ContravariantMonoidal]] functors are functors that supply - * a unit along the diagonal map for the `contramap2` operation. + * [[ContravariantMonoidal]] functors are functors that supply a unit along the diagonal map for the `contramap2` + * operation. * * Must obey the laws defined in cats.laws.ContravariantMonoidalLaws. * @@ -33,9 +33,8 @@ package cats trait ContravariantMonoidal[F[_]] extends ContravariantSemigroupal[F] with InvariantMonoidal[F] { /** - * `trivial` produces an instance of `F` for any type `A` - * that is trivial with respect to `contramap2` along - * the diagonal + * `trivial` produces an instance of `F` for any type `A` that is trivial with respect to `contramap2` along the + * diagonal */ def trivial[A]: F[A] = contramap(unit)(_ => ()) diff --git a/core/src/main/scala/cats/ContravariantSemigroupal.scala b/core/src/main/scala/cats/ContravariantSemigroupal.scala index 2b9d90e839..a19b220359 100644 --- a/core/src/main/scala/cats/ContravariantSemigroupal.scala +++ b/core/src/main/scala/cats/ContravariantSemigroupal.scala @@ -22,8 +22,8 @@ package cats /** - * [[ContravariantSemigroupal]] is nothing more than something both contravariant - * and Semigroupal. It comes up enough to be useful, and composes well + * [[ContravariantSemigroupal]] is nothing more than something both contravariant and Semigroupal. It comes up enough to + * be useful, and composes well */ trait ContravariantSemigroupal[F[_]] extends InvariantSemigroupal[F] with Contravariant[F] { self => override def composeFunctor[G[_]: Functor]: ContravariantSemigroupal[λ[α => F[G[α]]]] = diff --git a/core/src/main/scala/cats/Defer.scala b/core/src/main/scala/cats/Defer.scala index a4fd3da24d..e5fa1fa0b6 100644 --- a/core/src/main/scala/cats/Defer.scala +++ b/core/src/main/scala/cats/Defer.scala @@ -24,14 +24,11 @@ package cats import scala.util.control.TailCalls.TailRec /** - * Defer is a type class that shows the ability to defer creation - * inside of the type constructor F[_]. + * Defer is a type class that shows the ability to defer creation inside of the type constructor F[_]. * - * This comes up with F[_] types that are implemented with a trampoline - * or are based on function application. + * This comes up with F[_] types that are implemented with a trampoline or are based on function application. * - * The law is that defer(fa) is equivalent to fa, but not evaluated immediately, - * so + * The law is that defer(fa) is equivalent to fa, but not evaluated immediately, so * {{{ * scala> import cats._ * scala> import cats.syntax.all._ @@ -53,20 +50,16 @@ trait Defer[F[_]] extends Serializable { def defer[A](fa: => F[A]): F[A] /** - * Defer instances, like functions, parsers, generators, IO, etc... - * often are used in recursive settings where this function is useful + * Defer instances, like functions, parsers, generators, IO, etc... often are used in recursive settings where this + * function is useful * * fix(fn) == fn(fix(fn)) * * example: * - * val parser: P[Int] = - * Defer[P].fix[Int] { rec => - * CharsIn("0123456789") | P("(") ~ rec ~ P(")") - * } + * val parser: P[Int] = Defer[P].fix[Int] { rec => CharsIn("0123456789") | P("(") ~ rec ~ P(")") } * - * Note, fn may not yield a terminating value in which case both - * of the above F[A] run forever. + * Note, fn may not yield a terminating value in which case both of the above F[A] run forever. */ def fix[A](fn: F[A] => F[A]): F[A] = { lazy val res: F[A] = fn(defer(res)) @@ -74,20 +67,21 @@ trait Defer[F[_]] extends Serializable { } /** - * Useful when you want a recursive function that returns F where - * F[_]: Defer. Examples include IO, Eval, or transformers such - * as EitherT or OptionT. - * + * Useful when you want a recursive function that returns F where F[_]: Defer. Examples include IO, Eval, or + * transformers such as EitherT or OptionT. + * * example: * + * {{{ * val sumTo: Int => Eval[Int] = * Defer[Eval].recursiveFn[Int, Int] { recur => - * + * * { i => * if (i > 0) recur(i - 1).map(_ + i) * else Eval.now(0) * } * } + * }}} */ def recursiveFn[A, B](fn: (A => F[B]) => (A => F[B])): A => F[B] = new Function1[A, F[B]] { self => diff --git a/core/src/main/scala/cats/Eval.scala b/core/src/main/scala/cats/Eval.scala index f3b4f6776d..6890be3267 100644 --- a/core/src/main/scala/cats/Eval.scala +++ b/core/src/main/scala/cats/Eval.scala @@ -28,31 +28,26 @@ import scala.annotation.tailrec /** * Eval is a monad which controls evaluation. * - * This type wraps a value (or a computation that produces a value) - * and can produce it on command via the `.value` method. + * This type wraps a value (or a computation that produces a value) and can produce it on command via the `.value` + * method. * * There are three basic evaluation strategies: * - * - Now: evaluated immediately - * - Later: evaluated once when value is needed - * - Always: evaluated every time value is needed + * - Now: evaluated immediately + * - Later: evaluated once when value is needed + * - Always: evaluated every time value is needed * - * The Later and Always are both lazy strategies while Now is eager. - * Later and Always are distinguished from each other only by - * memoization: once evaluated Later will save the value to be returned - * immediately if it is needed again. Always will run its computation - * every time. + * The Later and Always are both lazy strategies while Now is eager. Later and Always are distinguished from each other + * only by memoization: once evaluated Later will save the value to be returned immediately if it is needed again. + * Always will run its computation every time. * - * Eval supports stack-safe lazy computation via the .map and .flatMap - * methods, which use an internal trampoline to avoid stack overflows. - * Computation done within .map and .flatMap is always done lazily, - * even when applied to a Now instance. + * Eval supports stack-safe lazy computation via the .map and .flatMap methods, which use an internal trampoline to + * avoid stack overflows. Computation done within .map and .flatMap is always done lazily, even when applied to a Now + * instance. * - * It is not generally good style to pattern-match on Eval instances. - * Rather, use .map and .flatMap to chain computation, and use .value - * to get the result when needed. It is also not good style to create - * Eval instances whose computation involves calling .value on another - * Eval instance -- this can defeat the trampolining and lead to stack + * It is not generally good style to pattern-match on Eval instances. Rather, use .map and .flatMap to chain + * computation, and use .value to get the result when needed. It is also not good style to create Eval instances whose + * computation involves calling .value on another Eval instance -- this can defeat the trampolining and lead to stack * overflows. */ sealed abstract class Eval[+A] extends Serializable { self => @@ -60,36 +55,29 @@ sealed abstract class Eval[+A] extends Serializable { self => /** * Evaluate the computation and return an A value. * - * For lazy instances (Later, Always), any necessary computation - * will be performed at this point. For eager instances (Now), a - * value will be immediately returned. + * For lazy instances (Later, Always), any necessary computation will be performed at this point. For eager instances + * (Now), a value will be immediately returned. */ def value: A /** - * Transform an Eval[A] into an Eval[B] given the transformation - * function `f`. + * Transform an Eval[A] into an Eval[B] given the transformation function `f`. * - * This call is stack-safe -- many .map calls may be chained without - * consumed additional stack during evaluation. + * This call is stack-safe -- many .map calls may be chained without consumed additional stack during evaluation. * - * Computation performed in f is always lazy, even when called on an - * eager (Now) instance. + * Computation performed in f is always lazy, even when called on an eager (Now) instance. */ def map[B](f: A => B): Eval[B] = flatMap(a => Now(f(a))) /** - * Lazily perform a computation based on an Eval[A], using the - * function `f` to produce an Eval[B] given an A. + * Lazily perform a computation based on an Eval[A], using the function `f` to produce an Eval[B] given an A. * - * This call is stack-safe -- many .flatMap calls may be chained - * without consumed additional stack during evaluation. It is also - * written to avoid left-association problems, so that repeated - * calls to .flatMap will be efficiently applied. + * This call is stack-safe -- many .flatMap calls may be chained without consumed additional stack during evaluation. + * It is also written to avoid left-association problems, so that repeated calls to .flatMap will be efficiently + * applied. * - * Computation performed in f is always lazy, even when called on an - * eager (Now) instance. + * Computation performed in f is always lazy, even when called on an eager (Now) instance. */ def flatMap[B](f: A => Eval[B]): Eval[B] = this match { @@ -122,11 +110,10 @@ sealed abstract class Eval[+A] extends Serializable { self => } /** - * Ensure that the result of the computation (if any) will be - * memoized. + * Ensure that the result of the computation (if any) will be memoized. * - * Practically, this means that when called on an Always[A] a - * Later[A] with an equivalent computation will be returned. + * Practically, this means that when called on an Always[A] a Later[A] with an equivalent computation will be + * returned. */ def memoize: Eval[A] } @@ -136,8 +123,8 @@ sealed abstract class Eval[+A] extends Serializable { self => * * In some sense it is equivalent to using a val. * - * This type should be used when an A value is already in hand, or - * when the computation to produce an A value is pure and very fast. + * This type should be used when an A value is already in hand, or when the computation to produce an A value is pure + * and very fast. */ final case class Now[+A](value: A) extends Eval.Leaf[A] { def memoize: Eval[A] = this @@ -146,16 +133,13 @@ final case class Now[+A](value: A) extends Eval.Leaf[A] { /** * Construct a lazy Eval[A] instance. * - * This type should be used for most "lazy" values. In some sense it - * is equivalent to using a lazy val. + * This type should be used for most "lazy" values. In some sense it is equivalent to using a lazy val. * - * When caching is not required or desired (e.g. if the value produced - * may be large) prefer Always. When there is no computation - * necessary, prefer Now. + * When caching is not required or desired (e.g. if the value produced may be large) prefer Always. When there is no + * computation necessary, prefer Now. * - * Once Later has been evaluated, the closure (and any values captured - * by the closure) will not be retained, and will be available for - * garbage collection. + * Once Later has been evaluated, the closure (and any values captured by the closure) will not be retained, and will be + * available for garbage collection. */ final class Later[+A](f: () => A) extends Eval.Leaf[A] { private[this] var thunk: () => A = f @@ -183,12 +167,10 @@ object Later { /** * Construct a lazy Eval[A] instance. * - * This type can be used for "lazy" values. In some sense it is - * equivalent to using a Function0 value. + * This type can be used for "lazy" values. In some sense it is equivalent to using a Function0 value. * - * This type will evaluate the computation every time the value is - * required. It should be avoided except when laziness is required and - * caching must be avoided. Generally, prefer Later. + * This type will evaluate the computation every time the value is required. It should be avoided except when laziness + * is required and caching must be avoided. Generally, prefer Later. */ final class Always[+A](f: () => A) extends Eval.Leaf[A] { def value: A = f() @@ -202,9 +184,7 @@ object Always { object Eval extends EvalInstances { /** - * A Leaf does not depend on any other Eval - * so calling .value does not trigger - * any flatMaps or defers + * A Leaf does not depend on any other Eval so calling .value does not trigger any flatMaps or defers */ sealed abstract class Leaf[+A] extends Eval[A] @@ -226,8 +206,8 @@ object Eval extends EvalInstances { /** * Defer a computation which produces an Eval[A] value. * - * This is useful when you want to delay execution of an expression - * which produces an Eval[A] value. Like .flatMap, it is stack-safe. + * This is useful when you want to delay execution of an expression which produces an Eval[A] value. Like .flatMap, it + * is stack-safe. */ def defer[A](a: => Eval[A]): Eval[A] = new Eval.Defer[A](() => a) {} @@ -235,49 +215,42 @@ object Eval extends EvalInstances { /** * Static Eval instance for common value `Unit`. * - * This can be useful in cases where the same value may be needed - * many times. + * This can be useful in cases where the same value may be needed many times. */ val Unit: Eval[Unit] = Now(()) /** * Static Eval instance for common value `true`. * - * This can be useful in cases where the same value may be needed - * many times. + * This can be useful in cases where the same value may be needed many times. */ val True: Eval[Boolean] = Now(true) /** * Static Eval instance for common value `false`. * - * This can be useful in cases where the same value may be needed - * many times. + * This can be useful in cases where the same value may be needed many times. */ val False: Eval[Boolean] = Now(false) /** * Static Eval instance for common value `0`. * - * This can be useful in cases where the same value may be needed - * many times. + * This can be useful in cases where the same value may be needed many times. */ val Zero: Eval[Int] = Now(0) /** * Static Eval instance for common value `1`. * - * This can be useful in cases where the same value may be needed - * many times. + * This can be useful in cases where the same value may be needed many times. */ val One: Eval[Int] = Now(1) /** - * Defer is a type of Eval[A] that is used to defer computations - * which produce Eval[A]. + * Defer is a type of Eval[A] that is used to defer computations which produce Eval[A]. * - * Users should not instantiate Defer instances themselves. Instead, - * they will be automatically created when needed. + * Users should not instantiate Defer instances themselves. Instead, they will be automatically created when needed. */ sealed abstract class Defer[A](val thunk: () => Eval[A]) extends Eval[A] { @@ -286,17 +259,13 @@ object Eval extends EvalInstances { } /** - * FlatMap is a type of Eval[A] that is used to chain computations - * involving .map and .flatMap. Along with Eval#flatMap it - * implements the trampoline that guarantees stack-safety. + * FlatMap is a type of Eval[A] that is used to chain computations involving .map and .flatMap. Along with + * Eval#flatMap it implements the trampoline that guarantees stack-safety. * - * Users should not instantiate FlatMap instances - * themselves. Instead, they will be automatically created when - * needed. + * Users should not instantiate FlatMap instances themselves. Instead, they will be automatically created when needed. * - * Unlike a traditional trampoline, the internal workings of the - * trampoline are not exposed. This allows a slightly more efficient - * implementation of the .value method. + * Unlike a traditional trampoline, the internal workings of the trampoline are not exposed. This allows a slightly + * more efficient implementation of the .value method. */ sealed abstract class FlatMap[A] extends Eval[A] { self => type Start diff --git a/core/src/main/scala/cats/FlatMap.scala b/core/src/main/scala/cats/FlatMap.scala index 0249d3cd8d..b2bfd70b1b 100644 --- a/core/src/main/scala/cats/FlatMap.scala +++ b/core/src/main/scala/cats/FlatMap.scala @@ -22,17 +22,15 @@ package cats /** - * FlatMap type class gives us flatMap, which allows us to have a value - * in a context (F[A]) and then feed that into a function that takes - * a normal value and returns a value in a context (A => F[B]). + * FlatMap type class gives us flatMap, which allows us to have a value in a context (F[A]) and then feed that into a + * function that takes a normal value and returns a value in a context (A => F[B]). * - * One motivation for separating this out from Monad is that there are - * situations where we can implement flatMap but not pure. For example, - * we can implement map or flatMap that transforms the values of Map[K, *], - * but we can't implement pure (because we wouldn't know what key to use - * when instantiating the new Map). + * One motivation for separating this out from Monad is that there are situations where we can implement flatMap but not + * pure. For example, we can implement map or flatMap that transforms the values of Map[K, *], but we can't implement + * pure (because we wouldn't know what key to use when instantiating the new Map). * - * @see See [[https://github.com/typelevel/cats/issues/3]] for some discussion. + * @see + * See [[https://github.com/typelevel/cats/issues/3]] for some discussion. * * Must obey the laws defined in cats.laws.FlatMapLaws. */ @@ -59,9 +57,9 @@ trait FlatMap[F[_]] extends Apply[F] with FlatMapArityFunctions[F] { flatMap(ffa)(fa => fa) /** - * Sequentially compose two actions, discarding any value produced by the first. This variant of - * [[productR]] also lets you define the evaluation strategy of the second action. For instance - * you can evaluate it only ''after'' the first action has finished: + * Sequentially compose two actions, discarding any value produced by the first. This variant of [[productR]] also + * lets you define the evaluation strategy of the second action. For instance you can evaluate it only ''after'' the + * first action has finished: * * {{{ * scala> import cats.Eval @@ -78,9 +76,9 @@ trait FlatMap[F[_]] extends Apply[F] with FlatMapArityFunctions[F] { private[cats] def followedByEval[A, B](fa: F[A])(fb: Eval[F[B]]): F[B] = productREval(fa)(fb) /** - * Sequentially compose two actions, discarding any value produced by the second. This variant of - * [[productL]] also lets you define the evaluation strategy of the second action. For instance - * you can evaluate it only ''after'' the first action has finished: + * Sequentially compose two actions, discarding any value produced by the second. This variant of [[productL]] also + * lets you define the evaluation strategy of the second action. For instance you can evaluate it only ''after'' the + * first action has finished: * * {{{ * scala> import cats.Eval @@ -147,8 +145,7 @@ trait FlatMap[F[_]] extends Apply[F] with FlatMapArityFunctions[F] { /** * Keeps calling `f` until a `scala.util.Right[B]` is returned. * - * Based on Phil Freeman's - * [[http://functorial.com/stack-safety-for-free/index.pdf Stack Safety for Free]]. + * Based on Phil Freeman's [[http://functorial.com/stack-safety-for-free/index.pdf Stack Safety for Free]]. * * Implementations of this method should use constant stack space relative to `f`. */ @@ -175,16 +172,14 @@ trait FlatMap[F[_]] extends Apply[F] with FlatMapArityFunctions[F] { flatMap(fa)(a => as(f(a), a)) /** - * Like an infinite loop of >> calls. This is most useful effect loops - * that you want to run forever in for instance a server. + * Like an infinite loop of >> calls. This is most useful effect loops that you want to run forever in for instance a + * server. * * This will be an infinite loop, or it will return an F[Nothing]. * - * Be careful using this. - * For instance, a List of length k will produce a list of length k^n at iteration - * n. This means if k = 0, we return an empty list, if k = 1, we loop forever - * allocating single element lists, but if we have a k > 1, we will allocate - * exponentially increasing memory and very quickly OOM. + * Be careful using this. For instance, a List of length k will produce a list of length k^n at iteration + * n. This means if k = 0, we return an empty list, if k = 1, we loop forever allocating single element lists, but + * if we have a k > 1, we will allocate exponentially increasing memory and very quickly OOM. */ def foreverM[A, B](fa: F[A]): F[B] = { @@ -195,9 +190,8 @@ trait FlatMap[F[_]] extends Apply[F] with FlatMapArityFunctions[F] { } /** - * iterateForeverM is almost exclusively useful for effect types. For instance, - * A may be some state, we may take the current state, run some effect to get - * a new state and repeat. + * iterateForeverM is almost exclusively useful for effect types. For instance, A may be some state, we may take the + * current state, run some effect to get a new state and repeat. */ def iterateForeverM[A, B](a: A)(f: A => F[A]): F[B] = @@ -206,9 +200,8 @@ trait FlatMap[F[_]] extends Apply[F] with FlatMapArityFunctions[F] { }) /** - * This repeats an F until we get defined values. This can be useful - * for polling type operations on State (or RNG) Monads, or in effect - * monads. + * This repeats an F until we get defined values. This can be useful for polling type operations on State (or RNG) + * Monads, or in effect monads. */ def untilDefinedM[A](foa: F[Option[A]]): F[A] = { diff --git a/core/src/main/scala/cats/Foldable.scala b/core/src/main/scala/cats/Foldable.scala index d83c8bb550..7df7175c1a 100644 --- a/core/src/main/scala/cats/Foldable.scala +++ b/core/src/main/scala/cats/Foldable.scala @@ -29,22 +29,19 @@ import Foldable.{sentinel, Source} /** * Data structures that can be folded to a summary value. * - * In the case of a collection (such as `List` or `Vector`), these - * methods will fold together (combine) the values contained in the - * collection to produce a single result. Most collection types have - * `foldLeft` methods, which will usually be used by the associated - * `Foldable[_]` instance. + * In the case of a collection (such as `List` or `Vector`), these methods will fold together (combine) the values + * contained in the collection to produce a single result. Most collection types have `foldLeft` methods, which will + * usually be used by the associated `Foldable[_]` instance. * - * Instances of Foldable should be ordered collections to allow for consistent folding. - * Use the `UnorderedFoldable` type class if you want to fold over unordered collections. + * Instances of Foldable should be ordered collections to allow for consistent folding. Use the `UnorderedFoldable` type + * class if you want to fold over unordered collections. * * Foldable[F] is implemented in terms of two basic methods: * - * - `foldLeft(fa, b)(f)` eagerly folds `fa` from left-to-right. - * - `foldRight(fa, b)(f)` lazily folds `fa` from right-to-left. + * - `foldLeft(fa, b)(f)` eagerly folds `fa` from left-to-right. + * - `foldRight(fa, b)(f)` lazily folds `fa` from right-to-left. * - * Beyond these it provides many other useful methods related to - * folding over F[A] values. + * Beyond these it provides many other useful methods related to folding over F[A] values. * * See: [[http://www.cs.nott.ac.uk/~pszgmh/fold.pdf A tutorial on the universality and expressiveness of fold]] */ @@ -79,13 +76,11 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Right associative lazy fold on `F` using the folding function 'f'. * - * This method evaluates `lb` lazily (in some cases it will not be - * needed), and returns a lazy value. We are using `(A, Eval[B]) => - * Eval[B]` to support laziness in a stack-safe way. Chained - * computation should be performed via .map and .flatMap. + * This method evaluates `lb` lazily (in some cases it will not be needed), and returns a lazy value. We are using + * `(A, Eval[B]) => Eval[B]` to support laziness in a stack-safe way. Chained computation should be performed via .map + * and .flatMap. * - * For more detailed information about how this method works see the - * documentation for `Eval[_]`. + * For more detailed information about how this method works see the documentation for `Eval[_]`. * * Example: * {{{ @@ -146,17 +141,19 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s } /** - * Reduce the elements of this structure down to a single value by applying - * the provided aggregation function in a left-associative manner. + * Reduce the elements of this structure down to a single value by applying the provided aggregation function in a + * left-associative manner. * - * @return `None` if the structure is empty, otherwise the result of combining - * the cumulative left-associative result of the `f` operation over all of the - * elements. + * @return + * `None` if the structure is empty, otherwise the result of combining the cumulative left-associative result of the + * `f` operation over all of the elements. * - * @see [[reduceRightOption]] for a right-associative alternative. + * @see + * [[reduceRightOption]] for a right-associative alternative. * - * @see [[Reducible#reduceLeft]] for a version that doesn't need to return an - * `Option` for structures that are guaranteed to be non-empty. + * @see + * [[Reducible#reduceLeft]] for a version that doesn't need to return an `Option` for structures that are guaranteed + * to be non-empty. * * Example: * {{{ @@ -174,17 +171,19 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s reduceLeftToOption(fa)(identity)(f) /** - * Reduce the elements of this structure down to a single value by applying - * the provided aggregation function in a right-associative manner. + * Reduce the elements of this structure down to a single value by applying the provided aggregation function in a + * right-associative manner. * - * @return `None` if the structure is empty, otherwise the result of combining - * the cumulative right-associative result of the `f` operation over the - * `A` elements. + * @return + * `None` if the structure is empty, otherwise the result of combining the cumulative right-associative result of + * the `f` operation over the `A` elements. * - * @see [[reduceLeftOption]] for a left-associative alternative + * @see + * [[reduceLeftOption]] for a left-associative alternative * - * @see [[Reducible#reduceRight]] for a version that doesn't need to return an - * `Option` for structures that are guaranteed to be non-empty. + * @see + * [[Reducible#reduceRight]] for a version that doesn't need to return an `Option` for structures that are + * guaranteed to be non-empty. * * Example: * {{{ @@ -204,13 +203,15 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Find the minimum `A` item in this structure according to the `Order[A]`. * - * @return `None` if the structure is empty, otherwise the minimum element - * wrapped in a `Some`. + * @return + * `None` if the structure is empty, otherwise the minimum element wrapped in a `Some`. * - * @see [[Reducible#minimum]] for a version that doesn't need to return an - * `Option` for structures that are guaranteed to be non-empty. + * @see + * [[Reducible#minimum]] for a version that doesn't need to return an `Option` for structures that are guaranteed to + * be non-empty. * - * @see [[maximumOption]] for maximum instead of minimum. + * @see + * [[maximumOption]] for maximum instead of minimum. */ def minimumOption[A](fa: F[A])(implicit A: Order[A]): Option[A] = reduceLeftOption(fa)(A.min) @@ -218,13 +219,15 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Find the maximum `A` item in this structure according to the `Order[A]`. * - * @return `None` if the structure is empty, otherwise the maximum element - * wrapped in a `Some`. + * @return + * `None` if the structure is empty, otherwise the maximum element wrapped in a `Some`. * - * @see [[Reducible#maximum]] for a version that doesn't need to return an - * `Option` for structures that are guaranteed to be non-empty. + * @see + * [[Reducible#maximum]] for a version that doesn't need to return an `Option` for structures that are guaranteed to + * be non-empty. * - * @see [[minimumOption]] for minimum instead of maximum. + * @see + * [[minimumOption]] for minimum instead of maximum. */ def maximumOption[A](fa: F[A])(implicit A: Order[A]): Option[A] = reduceLeftOption(fa)(A.max) @@ -232,13 +235,15 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Find the minimum `A` item in this structure according to an `Order.by(f)`. * - * @return `None` if the structure is empty, otherwise the minimum element - * wrapped in a `Some`. + * @return + * `None` if the structure is empty, otherwise the minimum element wrapped in a `Some`. * - * @see [[Reducible#minimumBy]] for a version that doesn't need to return an - * `Option` for structures that are guaranteed to be non-empty. + * @see + * [[Reducible#minimumBy]] for a version that doesn't need to return an `Option` for structures that are guaranteed + * to be non-empty. * - * @see [[maximumByOption]] for maximum instead of minimum. + * @see + * [[maximumByOption]] for maximum instead of minimum. */ def minimumByOption[A, B: Order](fa: F[A])(f: A => B): Option[A] = minimumOption(fa)(Order.by(f)) @@ -246,25 +251,29 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Find the maximum `A` item in this structure according to an `Order.by(f)`. * - * @return `None` if the structure is empty, otherwise the maximum element - * wrapped in a `Some`. + * @return + * `None` if the structure is empty, otherwise the maximum element wrapped in a `Some`. * - * @see [[Reducible#maximumBy]] for a version that doesn't need to return an - * `Option` for structures that are guaranteed to be non-empty. + * @see + * [[Reducible#maximumBy]] for a version that doesn't need to return an `Option` for structures that are guaranteed + * to be non-empty. * - * @see [[minimumByOption]] for minimum instead of maximum. + * @see + * [[minimumByOption]] for minimum instead of maximum. */ def maximumByOption[A, B: Order](fa: F[A])(f: A => B): Option[A] = maximumOption(fa)(Order.by(f)) /** - * Find all the minimum `A` items in this structure. - * For all elements in the result Order.eqv(x, y) is true. Preserves order. + * Find all the minimum `A` items in this structure. For all elements in the result Order.eqv(x, y) is true. Preserves + * order. * - * @see [[Reducible#minimumNel]] for a version that doesn't need to return an - * `Option` for structures that are guaranteed to be non-empty. + * @see + * [[Reducible#minimumNel]] for a version that doesn't need to return an `Option` for structures that are guaranteed + * to be non-empty. * - * @see [[maximumList]] for maximum instead of minimum. + * @see + * [[maximumList]] for maximum instead of minimum. */ def minimumList[A](fa: F[A])(implicit A: Order[A]): List[A] = foldLeft(fa, List.empty[A]) { @@ -274,13 +283,15 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s }.reverse /** - * Find all the maximum `A` items in this structure. - * For all elements in the result Order.eqv(x, y) is true. Preserves order. + * Find all the maximum `A` items in this structure. For all elements in the result Order.eqv(x, y) is true. Preserves + * order. * - * @see [[Reducible#maximumNel]] for a version that doesn't need to return an - * `Option` for structures that are guaranteed to be non-empty. + * @see + * [[Reducible#maximumNel]] for a version that doesn't need to return an `Option` for structures that are guaranteed + * to be non-empty. * - * @see [[minimumList]] for minimum instead of maximum. + * @see + * [[minimumList]] for minimum instead of maximum. */ def maximumList[A](fa: F[A])(implicit A: Order[A]): List[A] = foldLeft(fa, List.empty[A]) { @@ -290,25 +301,29 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s }.reverse /** - * Find all the minimum `A` items in this structure according to an `Order.by(f)`. - * For all elements in the result Order.eqv(x, y) is true. Preserves order. + * Find all the minimum `A` items in this structure according to an `Order.by(f)`. For all elements in the result + * Order.eqv(x, y) is true. Preserves order. * - * @see [[Reducible#minimumByNel]] for a version that doesn't need to return an - * `Option` for structures that are guaranteed to be non-empty. + * @see + * [[Reducible#minimumByNel]] for a version that doesn't need to return an `Option` for structures that are + * guaranteed to be non-empty. * - * @see [[maximumByList]] for maximum instead of minimum. + * @see + * [[maximumByList]] for maximum instead of minimum. */ def minimumByList[A, B: Order](fa: F[A])(f: A => B): List[A] = minimumList(fa)(Order.by(f)) /** - * Find all the maximum `A` items in this structure according to an `Order.by(f)`. - * For all elements in the result Order.eqv(x, y) is true. Preserves order. + * Find all the maximum `A` items in this structure according to an `Order.by(f)`. For all elements in the result + * Order.eqv(x, y) is true. Preserves order. * - * @see [[Reducible#maximumByNel]] for a version that doesn't need to return an - * `Option` for structures that are guaranteed to be non-empty. + * @see + * [[Reducible#maximumByNel]] for a version that doesn't need to return an `Option` for structures that are + * guaranteed to be non-empty. * - * @see [[minimumByList]] for minimum instead of maximum. + * @see + * [[minimumByList]] for minimum instead of maximum. */ def maximumByList[A, B: Order](fa: F[A])(f: A => B): List[A] = maximumList(fa)(Order.by(f)) @@ -341,8 +356,7 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s }.value /** - * Like `collectFirst` from `scala.collection.Traversable` but takes `A => Option[B]` - * instead of `PartialFunction`s. + * Like `collectFirst` from `scala.collection.Traversable` but takes `A => Option[B]` instead of `PartialFunction`s. * {{{ * scala> import cats.syntax.all._ * scala> val keys = List(1, 2, 4, 5) @@ -363,8 +377,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Monadic version of `collectFirstSome`. * - * If there are no elements, the result is `None`. `collectFirstSomeM` short-circuits, - * i.e. once a Some element is found, no further effects are produced. + * If there are no elements, the result is `None`. `collectFirstSomeM` short-circuits, i.e. once a Some element is + * found, no further effects are produced. * * For example: * {{{ @@ -447,31 +461,27 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Convert F[A] to an Iterable[A]. * - * This method may be overridden for the sake of performance, but implementers should take care - * not to force a full materialization of the collection. + * This method may be overridden for the sake of performance, but implementers should take care not to force a full + * materialization of the collection. */ def toIterable[A](fa: F[A]): Iterable[A] = cats.compat.FoldableCompat.toIterable(fa)(self) /** - * Fold implemented by mapping `A` values into `B` and then - * combining them using the given `Monoid[B]` instance. + * Fold implemented by mapping `A` values into `B` and then combining them using the given `Monoid[B]` instance. */ def foldMap[A, B](fa: F[A])(f: A => B)(implicit B: Monoid[B]): B = foldLeft(fa, B.empty)((b, a) => B.combine(b, f(a))) /** - * Perform a stack-safe monadic left fold from the source context `F` - * into the target monad `G`. + * Perform a stack-safe monadic left fold from the source context `F` into the target monad `G`. * - * This method can express short-circuiting semantics. Even when - * `fa` is an infinite structure, this method can potentially - * terminate if the `foldRight` implementation for `F` and the - * `tailRecM` implementation for `G` are sufficiently lazy. + * This method can express short-circuiting semantics. Even when `fa` is an infinite structure, this method can + * potentially terminate if the `foldRight` implementation for `F` and the `tailRecM` implementation for `G` are + * sufficiently lazy. * - * Instances for concrete structures (e.g. `List`) will often - * have a more efficient implementation than the default one - * in terms of `foldRight`. + * Instances for concrete structures (e.g. `List`) will often have a more efficient implementation than the default + * one in terms of `foldRight`. */ def foldM[G[_], A, B](fa: F[A], z: B)(f: (B, A) => G[B])(implicit G: Monad[G]): G[B] = { val src = Foldable.Source.fromFoldable(fa)(self) @@ -501,8 +511,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s foldMapA(fga)(identity) /** - * Fold implemented by mapping `A` values into `B` in a context `G` and then - * combining them using the `MonoidK[G]` instance. + * Fold implemented by mapping `A` values into `B` in a context `G` and then combining them using the `MonoidK[G]` + * instance. * * {{{ * scala> import cats._, cats.implicits._ @@ -525,8 +535,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s foldM(fa, z)(f) /** - * Monadic folding on `F` by mapping `A` values to `G[B]`, combining the `B` - * values using the given `Monoid[B]` instance. + * Monadic folding on `F` by mapping `A` values to `G[B]`, combining the `B` values using the given `Monoid[B]` + * instance. * * Similar to [[foldM]], but using a `Monoid[B]`. Will typically be more efficient than [[foldMapA]]. * @@ -546,8 +556,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s foldM(fa, B.empty)((b, a) => G.map(f(a))(B.combine(b, _))) /** - * Fold in an [[Applicative]] context by mapping the `A` values to `G[B]`. combining - * the `B` values using the given `Monoid[B]` instance. + * Fold in an [[Applicative]] context by mapping the `A` values to `G[B]`. combining the `B` values using the given + * `Monoid[B]` instance. * * Similar to [[foldMapM]], but will typically be less efficient. * @@ -569,8 +579,7 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Traverse `F[A]` using `Applicative[G]`. * - * `A` values will be mapped into `G[B]` and combined using - * `Applicative#map2`. + * `A` values will be mapped into `G[B]` and combined using `Applicative#map2`. * * For example: * @@ -584,9 +593,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s * res1: Option[Unit] = None * }}} * - * This method is primarily useful when `G[_]` represents an action - * or effect, and the specific `A` aspect of `G[A]` is not otherwise - * needed. + * This method is primarily useful when `G[_]` represents an action or effect, and the specific `A` aspect of `G[A]` + * is not otherwise needed. */ def traverseVoid[G[_], A, B](fa: F[A])(f: A => G[B])(implicit G: Applicative[G]): G[Unit] = foldRight(fa, Always(G.unit)) { (a, acc) => @@ -598,7 +606,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Alias for `traverseVoid`. * - * @deprecated this method should be considered as deprecated and replaced by `traverseVoid`. + * @deprecated + * this method should be considered as deprecated and replaced by `traverseVoid`. */ def traverse_[G[_], A, B](fa: F[A])(f: A => G[B])(implicit G: Applicative[G]): G[Unit] = traverseVoid(fa)(f) @@ -606,8 +615,7 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Sequence `F[G[A]]` using `Applicative[G]`. * - * This is similar to `traverseVoid` except it operates on `F[G[A]]` - * values, so no additional functions are needed. + * This is similar to `traverseVoid` except it operates on `F[G[A]]` values, so no additional functions are needed. * * For example: * @@ -626,7 +634,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Alias for `sequenceVoid`. * - * @deprecated this method should be considered as deprecated and replaced by `sequenceVoid`. + * @deprecated + * this method should be considered as deprecated and replaced by `sequenceVoid`. */ def sequence_[G[_]: Applicative, A](fga: F[G[A]]): G[Unit] = sequenceVoid(fga) @@ -634,8 +643,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Fold implemented using the given `MonoidK[G]` instance. * - * This method is identical to fold, except that we use the universal monoid (`MonoidK[G]`) - * to get a `Monoid[G[A]]` instance. + * This method is identical to fold, except that we use the universal monoid (`MonoidK[G]`) to get a `Monoid[G[A]]` + * instance. * * For example: * @@ -658,8 +667,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Find the first element matching the effectful predicate, if one exists. * - * If there are no elements, the result is `None`. `findM` short-circuits, - * i.e. once an element is found, no further effects are produced. + * If there are no elements, the result is `None`. `findM` short-circuits, i.e. once an element is found, no further + * effects are produced. * * For example: * {{{ @@ -704,8 +713,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Check whether at least one element satisfies the effectful predicate. * - * If there are no elements, the result is `false`. `existsM` short-circuits, - * i.e. once a `true` result is encountered, no further effects are produced. + * If there are no elements, the result is `false`. `existsM` short-circuits, i.e. once a `true` result is + * encountered, no further effects are produced. * * For example: * @@ -739,8 +748,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s /** * Check whether all elements satisfy the effectful predicate. * - * If there are no elements, the result is `true`. `forallM` short-circuits, - * i.e. once a `false` result is encountered, no further effects are produced. + * If there are no elements, the result is `true`. `forallM` short-circuits, i.e. once a `false` result is + * encountered, no further effects are produced. * * For example: * @@ -780,8 +789,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s }.toList /** - * Separate this Foldable into a Tuple by a separating function `A => Either[B, C]` - * Equivalent to `Functor#map` and then `Alternative#separate`. + * Separate this Foldable into a Tuple by a separating function `A => Either[B, C]` Equivalent to `Functor#map` and + * then `Alternative#separate`. * * {{{ * scala> import cats.syntax.all._ @@ -813,15 +822,13 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s }.toList /** - * Convert F[A] to a List[A], retaining only initial elements which - * match `p`. + * Convert F[A] to a List[A], retaining only initial elements which match `p`. */ def takeWhile_[A](fa: F[A])(p: A => Boolean): List[A] = toIterable(fa).iterator.takeWhile(p).toList /** - * Convert F[A] to a List[A], dropping all initial elements which - * match `p`. + * Convert F[A] to a List[A], dropping all initial elements which match `p`. */ def dropWhile_[A](fa: F[A])(p: A => Boolean): List[A] = foldLeft(fa, mutable.ListBuffer.empty[A]) { (buf, a) => @@ -883,8 +890,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s foldMap(fa)(f) /** - * Separate this Foldable into a Tuple by a separating function `A => H[B, C]` for some `Bifoldable[H]` - * Equivalent to `Functor#map` and then `Alternative#separate`. + * Separate this Foldable into a Tuple by a separating function `A => H[B, C]` for some `Bifoldable[H]` Equivalent to + * `Functor#map` and then `Alternative#separate`. * * {{{ * scala> import cats.syntax.all._, cats.Foldable, cats.data.Const @@ -938,8 +945,8 @@ trait Foldable[F[_]] extends UnorderedFoldable[F] with FoldableNFunctions[F] { s } /** - * Separate this Foldable into a Tuple by an effectful separating function `A => G[Either[B, C]]` - * Equivalent to `Traverse#traverse` over `Alternative#separate` + * Separate this Foldable into a Tuple by an effectful separating function `A => G[Either[B, C]]` Equivalent to + * `Traverse#traverse` over `Alternative#separate` * * {{{ * scala> import cats.syntax.all._, cats.Foldable, cats.Eval @@ -986,12 +993,11 @@ object Foldable { /** * Isomorphic to * - * type Source[+A] = () => Option[(A, Source[A])] + * type Source[+A] = () => Option[(A, Source[A])] * * (except that recursive type aliases are not allowed). * - * It could be made a value class after - * https://github.com/scala/bug/issues/9600 is resolved. + * It could be made a value class after https://github.com/scala/bug/issues/9600 is resolved. */ sealed abstract private[cats] class Source[+A] { def uncons: Option[(A, Eval[Source[A]])] diff --git a/core/src/main/scala/cats/Functor.scala b/core/src/main/scala/cats/Functor.scala index dbfd70cd0b..60ff95fca8 100644 --- a/core/src/main/scala/cats/Functor.scala +++ b/core/src/main/scala/cats/Functor.scala @@ -36,8 +36,8 @@ trait Functor[F[_]] extends Invariant[F] { self => // derived methods /** - * Alias for [[map]], since [[map]] can't be injected as syntax if - * the implementing type already had a built-in `.map` method. + * Alias for [[map]], since [[map]] can't be injected as syntax if the implementing type already had a built-in `.map` + * method. * * Example: * {{{ @@ -54,13 +54,11 @@ trait Functor[F[_]] extends Invariant[F] { self => /** * Lifts natural subtyping covariance of covariant Functors. * - * NOTE: In certain (perhaps contrived) situations that rely on universal - * equality this can result in a `ClassCastException`, because it is - * implemented as a type cast. It could be implemented as `map(identity)`, but - * according to the functor laws, that should be equal to `fa`, and a type - * cast is often much more performant. - * See [[https://github.com/typelevel/cats/issues/1080#issuecomment-225892635 this example]] - * of `widen` creating a `ClassCastException`. + * NOTE: In certain (perhaps contrived) situations that rely on universal equality this can result in a + * `ClassCastException`, because it is implemented as a type cast. It could be implemented as `map(identity)`, but + * according to the functor laws, that should be equal to `fa`, and a type cast is often much more performant. See + * [[https://github.com/typelevel/cats/issues/1080#issuecomment-225892635 this example]] of `widen` creating a + * `ClassCastException`. * * Example: * {{{ @@ -102,8 +100,7 @@ trait Functor[F[_]] extends Invariant[F] { self => def void[A](fa: F[A]): F[Unit] = as(fa, ()) /** - * Tuple the values in fa with the result of applying a function - * with the value + * Tuple the values in fa with the result of applying a function with the value * * Example: * {{{ @@ -116,7 +113,7 @@ trait Functor[F[_]] extends Invariant[F] { self => def fproduct[A, B](fa: F[A])(f: A => B): F[(A, B)] = map(fa)(a => a -> f(a)) /** - * Pair the result of function application with `A`. + * Pair the result of function application with `A`. * * Example: * {{{ @@ -171,8 +168,7 @@ trait Functor[F[_]] extends Invariant[F] { self => def tupleRight[A, B](fa: F[A], b: B): F[(A, B)] = map(fa)(a => (a, b)) /** - * Modifies the `A` value in `F[A]` with the supplied function, if the function is defined for the value. - * Example: + * Modifies the `A` value in `F[A]` with the supplied function, if the function is defined for the value. Example: * {{{ * scala> import cats.syntax.all._ * diff --git a/core/src/main/scala/cats/FunctorFilter.scala b/core/src/main/scala/cats/FunctorFilter.scala index df13f9a734..0a037b75e9 100644 --- a/core/src/main/scala/cats/FunctorFilter.scala +++ b/core/src/main/scala/cats/FunctorFilter.scala @@ -31,9 +31,8 @@ trait FunctorFilter[F[_]] extends Serializable { def functor: Functor[F] /** - * A combined `map` and `filter`. Filtering is handled via `Option` - * instead of `Boolean` such that the output type `B` can be different than - * the input type `A`. + * A combined `map` and `filter`. Filtering is handled via `Option` instead of `Boolean` such that the output type `B` + * can be different than the input type `A`. * * Example: * {{{ @@ -48,8 +47,7 @@ trait FunctorFilter[F[_]] extends Serializable { def mapFilter[A, B](fa: F[A])(f: A => Option[B]): F[B] /** - * Similar to [[mapFilter]] but uses a partial function instead of a function - * that returns an `Option`. + * Similar to [[mapFilter]] but uses a partial function instead of a function that returns an `Option`. * * Example: * {{{ @@ -66,8 +64,7 @@ trait FunctorFilter[F[_]] extends Serializable { mapFilter(fa)(f.lift) /** - * "Flatten" out a structure by collapsing `Option`s. - * Equivalent to using `mapFilter` with `identity`. + * "Flatten" out a structure by collapsing `Option`s. Equivalent to using `mapFilter` with `identity`. * * Example: * {{{ @@ -81,16 +78,15 @@ trait FunctorFilter[F[_]] extends Serializable { mapFilter(fa)(identity) /** - * Apply a filter to a structure such that the output structure contains all - * `A` elements in the input structure that satisfy the predicate `f` but none - * that don't. + * Apply a filter to a structure such that the output structure contains all `A` elements in the input structure that + * satisfy the predicate `f` but none that don't. */ def filter[A](fa: F[A])(f: A => Boolean): F[A] = mapFilter(fa)(a => if (f(a)) Some(a) else None) /** - * Apply a filter to a structure such that the output structure contains all - * `A` elements in the input structure that do not satisfy the predicate `f`. + * Apply a filter to a structure such that the output structure contains all `A` elements in the input structure that + * do not satisfy the predicate `f`. */ def filterNot[A](fa: F[A])(f: A => Boolean): F[A] = mapFilter(fa)(Some(_).filterNot(f)) diff --git a/core/src/main/scala/cats/Inject.scala b/core/src/main/scala/cats/Inject.scala index 54b9b27896..ba493611a0 100644 --- a/core/src/main/scala/cats/Inject.scala +++ b/core/src/main/scala/cats/Inject.scala @@ -22,19 +22,19 @@ package cats /** - * Inject is a type class providing an injection from type `A` into - * type `B`. An injection is a function `inj` which does not destroy - * any information: for every `b: B` there is at most one `a: A` such - * that `inj(a) = b`. + * Inject is a type class providing an injection from type `A` into type `B`. An injection is a function `inj` which + * does not destroy any information: for every `b: B` there is at most one `a: A` such that `inj(a) = b`. * - * Because of this all injections admit partial inverses `prj` which - * pair a value `b: B` back with a single value `a: A`. + * Because of this all injections admit partial inverses `prj` which pair a value `b: B` back with a single value + * `a: A`. * * @since 1.0 - * @note Prior to cats 1.0, Inject handled injection for type - * constructors. For injection of type constructors, use [[InjectK]]. + * @note + * Prior to cats 1.0, Inject handled injection for type constructors. For injection of type constructors, use + * [[InjectK]]. * - * @see [[InjectK]] for injection for [[cats.data.EitherK]] + * @see + * [[InjectK]] for injection for [[cats.data.EitherK]] */ abstract class Inject[A, B] { def inj: A => B diff --git a/core/src/main/scala/cats/InjectK.scala b/core/src/main/scala/cats/InjectK.scala index 71f7a016a5..5b6c55358b 100644 --- a/core/src/main/scala/cats/InjectK.scala +++ b/core/src/main/scala/cats/InjectK.scala @@ -25,23 +25,23 @@ import cats.arrow.FunctionK import cats.data.EitherK /** - * InjectK is a type class providing an injection from type - * constructor `F` into type constructor `G`. An injection is a - * functor transformation `inj` which does not destroy any - * information: for every `ga: G[A]` there is at most one `fa: F[A]` - * such that `inj(fa) = ga`. + * InjectK is a type class providing an injection from type constructor `F` into type constructor `G`. An injection is a + * functor transformation `inj` which does not destroy any information: for every `ga: G[A]` there is at most one + * `fa: F[A]` such that `inj(fa) = ga`. * - * Because of this all injections admit partial inverses `prj` which - * pair a value `ga: G[A]` back with a single value `fa: F[A]`. + * Because of this all injections admit partial inverses `prj` which pair a value `ga: G[A]` back with a single value + * `fa: F[A]`. * - * The behavior of the default instances for the InjectK type class - * are described thoroughly in "Data types a la carte" (Swierstra - * 2008). + * The behavior of the default instances for the InjectK type class are described thoroughly in "Data types a la carte" + * (Swierstra 2008). * - * @note Prior to cats 1.0, InjectK was known as [[Inject]]. + * @note + * Prior to cats 1.0, InjectK was known as [[Inject]]. * - * @see [[http://www.staff.science.uu.nl/~swier004/publications/2008-jfp.pdf]] - * @see [[Inject]] for injection for `Either` + * @see + * [[http://www.staff.science.uu.nl/~swier004/publications/2008-jfp.pdf]] + * @see + * [[Inject]] for injection for `Either` */ abstract class InjectK[F[_], G[_]] { def inj: FunctionK[F, G] diff --git a/core/src/main/scala/cats/Invariant.scala b/core/src/main/scala/cats/Invariant.scala index f758c3cd23..6f96cedbf0 100644 --- a/core/src/main/scala/cats/Invariant.scala +++ b/core/src/main/scala/cats/Invariant.scala @@ -37,8 +37,7 @@ import scala.util.control.TailCalls.TailRec trait Invariant[F[_]] extends Serializable { self => /** - * Transform an `F[A]` into an `F[B]` by providing a transformation from `A` - * to `B` and one from `B` to `A`. + * Transform an `F[A]` into an `F[B]` by providing a transformation from `A` to `B` and one from `B` to `A`. * * Example: * {{{ @@ -74,8 +73,7 @@ trait Invariant[F[_]] extends Serializable { self => } /** - * Compose Invariant `F[_]` and Functor `G[_]` then produce `Invariant[F[G[_]]]` - * using F's `imap` and G's `map`. + * Compose Invariant `F[_]` and Functor `G[_]` then produce `Invariant[F[G[_]]]` using F's `imap` and G's `map`. * * Example: * {{{ @@ -97,8 +95,8 @@ trait Invariant[F[_]] extends Serializable { self => } /** - * Compose Invariant `F[_]` and Contravariant `G[_]` then produce `Invariant[F[G[_]]]` - * using F's `imap` and G's `contramap`. + * Compose Invariant `F[_]` and Contravariant `G[_]` then produce `Invariant[F[G[_]]]` using F's `imap` and G's + * `contramap`. * * Example: * {{{ @@ -156,12 +154,13 @@ object Invariant extends ScalaVersionSpecificInvariantInstances with InvariantIn /** * @deprecated - * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone - * (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). - * We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]]. - * However, at this time there are no plans to remove these instances from Cats. + * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone (particularly the semantics of + * [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). We recommend using + * [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of + * [[scala.concurrent.Future Future]]. However, at this time there are no plans to remove these instances from Cats. * - * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] + * @see + * [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] */ implicit def catsInstancesForFuture(implicit ec: ExecutionContext diff --git a/core/src/main/scala/cats/InvariantSemigroupal.scala b/core/src/main/scala/cats/InvariantSemigroupal.scala index dc504363d3..6119cf33a0 100644 --- a/core/src/main/scala/cats/InvariantSemigroupal.scala +++ b/core/src/main/scala/cats/InvariantSemigroupal.scala @@ -22,8 +22,8 @@ package cats /** - * [[InvariantSemigroupal]] is nothing more than something both invariant - * and Semigroupal. It comes up enough to be useful, and composes well + * [[InvariantSemigroupal]] is nothing more than something both invariant and Semigroupal. It comes up enough to be + * useful, and composes well */ trait InvariantSemigroupal[F[_]] extends Semigroupal[F] with Invariant[F] { self => diff --git a/core/src/main/scala/cats/Monad.scala b/core/src/main/scala/cats/Monad.scala index c694f854e3..b7e08b82be 100644 --- a/core/src/main/scala/cats/Monad.scala +++ b/core/src/main/scala/cats/Monad.scala @@ -35,11 +35,10 @@ trait Monad[F[_]] extends FlatMap[F] with Applicative[F] { flatMap(fa)(a => pure(f(a))) /** - * Execute an action repeatedly as long as the given `Boolean` expression - * returns `true`. The condition is evaluated before the loop body. - * Collects the results into an arbitrary `Alternative` value, such as a `Vector`. - * This implementation uses append on each evaluation result, - * so avoid data structures with non-constant append performance, e.g. `List`. + * Execute an action repeatedly as long as the given `Boolean` expression returns `true`. The condition is evaluated + * before the loop body. Collects the results into an arbitrary `Alternative` value, such as a `Vector`. This + * implementation uses append on each evaluation result, so avoid data structures with non-constant append + * performance, e.g. `List`. */ def whileM[G[_], A](p: F[Boolean])(body: => F[A])(implicit G: Alternative[G]): F[G[A]] = { @@ -57,9 +56,8 @@ trait Monad[F[_]] extends FlatMap[F] with Applicative[F] { } /** - * Execute an action repeatedly as long as the given `Boolean` expression - * returns `true`. The condition is evaluated before the loop body. - * Discards results. + * Execute an action repeatedly as long as the given `Boolean` expression returns `true`. The condition is evaluated + * before the loop body. Discards results. */ def whileM_[A](p: F[Boolean])(body: => F[A]): F[Unit] = { @@ -75,11 +73,9 @@ trait Monad[F[_]] extends FlatMap[F] with Applicative[F] { } /** - * Execute an action repeatedly until the `Boolean` condition returns `true`. - * The condition is evaluated after the loop body. Collects results into an - * arbitrary `Alternative` value, such as a `Vector`. - * This implementation uses append on each evaluation result, - * so avoid data structures with non-constant append performance, e.g. `List`. + * Execute an action repeatedly until the `Boolean` condition returns `true`. The condition is evaluated after the + * loop body. Collects results into an arbitrary `Alternative` value, such as a `Vector`. This implementation uses + * append on each evaluation result, so avoid data structures with non-constant append performance, e.g. `List`. */ def untilM[G[_], A](f: F[A])(cond: => F[Boolean])(implicit G: Alternative[G]): F[G[A]] = { val p = Eval.later(cond) @@ -87,8 +83,8 @@ trait Monad[F[_]] extends FlatMap[F] with Applicative[F] { } /** - * Execute an action repeatedly until the `Boolean` condition returns `true`. - * The condition is evaluated after the loop body. Discards results. + * Execute an action repeatedly until the `Boolean` condition returns `true`. The condition is evaluated after the + * loop body. Discards results. */ def untilM_[A](f: F[A])(cond: => F[Boolean]): F[Unit] = { val p = Eval.later(cond) @@ -96,8 +92,8 @@ trait Monad[F[_]] extends FlatMap[F] with Applicative[F] { } /** - * Execute an action repeatedly until its result fails to satisfy the given predicate - * and return that result, discarding all others. + * Execute an action repeatedly until its result fails to satisfy the given predicate and return that result, + * discarding all others. */ def iterateWhile[A](f: F[A])(p: A => Boolean): F[A] = flatMap(f) { i => @@ -105,8 +101,8 @@ trait Monad[F[_]] extends FlatMap[F] with Applicative[F] { } /** - * Execute an action repeatedly until its result satisfies the given predicate - * and return that result, discarding all others. + * Execute an action repeatedly until its result satisfies the given predicate and return that result, discarding all + * others. */ def iterateUntil[A](f: F[A])(p: A => Boolean): F[A] = flatMap(f) { i => @@ -114,8 +110,7 @@ trait Monad[F[_]] extends FlatMap[F] with Applicative[F] { } /** - * Apply a monadic function iteratively until its result fails - * to satisfy the given predicate and return that result. + * Apply a monadic function iteratively until its result fails to satisfy the given predicate and return that result. */ def iterateWhileM[A](init: A)(f: A => F[A])(p: A => Boolean): F[A] = tailRecM(init) { a => @@ -126,16 +121,14 @@ trait Monad[F[_]] extends FlatMap[F] with Applicative[F] { } /** - * Apply a monadic function iteratively until its result satisfies - * the given predicate and return that result. + * Apply a monadic function iteratively until its result satisfies the given predicate and return that result. */ def iterateUntilM[A](init: A)(f: A => F[A])(p: A => Boolean): F[A] = iterateWhileM(init)(f)(!p(_)) /** - * Simulates an if/else-if/else in the context of an F. It evaluates conditions until - * one evaluates to true, and returns the associated F[A]. If no condition is true, - * returns els. + * Simulates an if/else-if/else in the context of an F. It evaluates conditions until one evaluates to true, and + * returns the associated F[A]. If no condition is true, returns els. * * {{{ * scala> import cats._ @@ -145,7 +138,8 @@ trait Monad[F[_]] extends FlatMap[F] with Applicative[F] { * * Based on a [[https://gist.github.com/1b92a6e338f4e1537692e748c54b9743 gist]] by Daniel Spiewak with a stack-safe * [[https://github.com/typelevel/cats/pull/3553#discussion_r468121480 implementation]] due to P. Oscar Boykin - * @see See [[https://gitter.im/typelevel/cats-effect?at=5f297e4314c413356f56d230]] for the discussion. + * @see + * See [[https://gitter.im/typelevel/cats-effect?at=5f297e4314c413356f56d230]] for the discussion. */ def ifElseM[A](branches: (F[Boolean], F[A])*)(els: F[A]): F[A] = { @@ -163,8 +157,7 @@ trait Monad[F[_]] extends FlatMap[F] with Applicative[F] { } /** - * Modifies the `A` value in `F[A]` with the supplied function, if the function is defined for the value. - * Example: + * Modifies the `A` value in `F[A]` with the supplied function, if the function is defined for the value. Example: * {{{ * scala> import cats.syntax.all._ * diff --git a/core/src/main/scala/cats/MonadError.scala b/core/src/main/scala/cats/MonadError.scala index c6e1bfa136..93527a333a 100644 --- a/core/src/main/scala/cats/MonadError.scala +++ b/core/src/main/scala/cats/MonadError.scala @@ -61,12 +61,10 @@ trait MonadError[F[_], E] extends ApplicativeError[F, E] with Monad[F] { flatMap(fa)(_.fold(raiseError, pure)) /** - * Returns a new value that transforms the result of the source, - * given the `recover` or `bind` functions, which get executed depending - * on whether the result is successful or if it ends in error. + * Returns a new value that transforms the result of the source, given the `recover` or `bind` functions, which get + * executed depending on whether the result is successful or if it ends in error. * - * This is an optimization on usage of [[attempt]] and [[flatMap]], - * this equivalence being available: + * This is an optimization on usage of [[attempt]] and [[flatMap]], this equivalence being available: * * {{{ * fa.redeemWith(fe, fs) <-> fa.attempt.flatMap(_.fold(fe, fs)) @@ -84,23 +82,24 @@ trait MonadError[F[_], E] extends ApplicativeError[F, E] with Monad[F] { * fa.redeemWith(F.raiseError, fs) <-> fa.flatMap(fs) * }}} * - * Implementations are free to override it in order to optimize - * error recovery. + * Implementations are free to override it in order to optimize error recovery. * - * @see [[redeem]], [[attempt]] and [[handleErrorWith]] + * @see + * [[redeem]], [[attempt]] and [[handleErrorWith]] * - * @param fa is the source whose result is going to get transformed - * @param recover is the function that gets called to recover the source - * in case of error - * @param bind is the function that gets to transform the source - * in case of success + * @param fa + * is the source whose result is going to get transformed + * @param recover + * is the function that gets called to recover the source in case of error + * @param bind + * is the function that gets to transform the source in case of success */ def redeemWith[A, B](fa: F[A])(recover: E => F[B], bind: A => F[B]): F[B] = flatMap(attempt(fa))(_.fold(recover, bind)) /** - * Reifies the value or error of the source and performs an effect on the result, - * then recovers the original value or error back into `F`. + * Reifies the value or error of the source and performs an effect on the result, then recovers the original value or + * error back into `F`. * * Note that if the effect returned by `f` fails, the resulting effect will fail too. * diff --git a/core/src/main/scala/cats/MonoidK.scala b/core/src/main/scala/cats/MonoidK.scala index f35c97e15f..7a2713193f 100644 --- a/core/src/main/scala/cats/MonoidK.scala +++ b/core/src/main/scala/cats/MonoidK.scala @@ -26,22 +26,18 @@ import cats.kernel.compat.scalaVersionSpecific.* /** * MonoidK is a universal monoid which operates on kinds. * - * This type class is useful when its type parameter F[_] has a - * structure that can be combined for any particular type, and which - * also has an "empty" representation. Thus, MonoidK is like a Monoid - * for kinds (i.e. parametrized types). + * This type class is useful when its type parameter F[_] has a structure that can be combined for any particular type, + * and which also has an "empty" representation. Thus, MonoidK is like a Monoid for kinds (i.e. parametrized types). * * A MonoidK[F] can produce a Monoid[F[A]] for any type A. * * Here's how to distinguish Monoid and MonoidK: * - * - Monoid[A] allows A values to be combined, and also means there - * is an "empty" A value that functions as an identity. - * - * - MonoidK[F] allows two F[A] values to be combined, for any A. It - * also means that for any A, there is an "empty" F[A] value. The - * combination operation and empty value just depend on the - * structure of F, but not on the structure of A. + * - Monoid[A] allows A values to be combined, and also means there is an "empty" A value that functions as an + * identity. + * - MonoidK[F] allows two F[A] values to be combined, for any A. It also means that for any A, there is an "empty" + * F[A] value. The combination operation and empty value just depend on the structure of F, but not on the structure + * of A. */ trait MonoidK[F[_]] extends SemigroupK[F] { self => @@ -111,10 +107,9 @@ trait MonoidK[F[_]] extends SemigroupK[F] { self => * {{{ * scala> SemigroupK[List].combineNK(List(1), 5) * res0: List[Int] = List(1, 1, 1, 1, 1) - + * * scala> MonoidK[List].combineNK(List("ha"), 0) * res1: List[String] = List() - * * }}} */ override def combineNK[A](a: F[A], n: Int): F[A] = diff --git a/core/src/main/scala/cats/NonEmptyReducible.scala b/core/src/main/scala/cats/NonEmptyReducible.scala index ebce0529f3..08ea07bf40 100644 --- a/core/src/main/scala/cats/NonEmptyReducible.scala +++ b/core/src/main/scala/cats/NonEmptyReducible.scala @@ -25,14 +25,14 @@ import cats.Foldable.Source import cats.data.NonEmptyList /** - * This class defines a `Reducible[F]` in terms of a `Foldable[G]` - * together with a `split` method, `F[A]` => `(A, G[A])`. + * This class defines a `Reducible[F]` in terms of a `Foldable[G]` together with a `split` method, `F[A]` => + * `(A, G[A])`. * - * This class can be used on any type where the first value (`A`) and - * the "rest" of the values (`G[A]`) can be easily found. + * This class can be used on any type where the first value (`A`) and the "rest" of the values (`G[A]`) can be easily + * found. * - * This class is only a helper, does not define a typeclass and should not be used outside of Cats. - * Also see the discussion: PR #3541 and issue #3069. + * This class is only a helper, does not define a typeclass and should not be used outside of Cats. Also see the + * discussion: PR #3541 and issue #3069. */ abstract class NonEmptyReducible[F[_], G[_]](implicit override protected[cats] val G: Foldable[G] diff --git a/core/src/main/scala/cats/NonEmptyTraverse.scala b/core/src/main/scala/cats/NonEmptyTraverse.scala index fe0beea466..ad635cd86e 100644 --- a/core/src/main/scala/cats/NonEmptyTraverse.scala +++ b/core/src/main/scala/cats/NonEmptyTraverse.scala @@ -24,15 +24,14 @@ package cats /** * NonEmptyTraverse, also known as Traversable1. * - * `NonEmptyTraverse` is like a non-empty `Traverse`. In addition to the traverse and sequence - * methods it provides nonEmptyTraverse and nonEmptySequence methods which require an `Apply` instance instead of `Applicative`. + * `NonEmptyTraverse` is like a non-empty `Traverse`. In addition to the traverse and sequence methods it provides + * nonEmptyTraverse and nonEmptySequence methods which require an `Apply` instance instead of `Applicative`. */ trait NonEmptyTraverse[F[_]] extends Traverse[F] with Reducible[F] { self => /** - * Given a function which returns a G effect, thread this effect - * through the running of this function on all the values in F, - * returning an F[B] in a G context. + * Given a function which returns a G effect, thread this effect through the running of this function on all the + * values in F, returning an F[B] in a G context. * * Example: * {{{ @@ -50,8 +49,7 @@ trait NonEmptyTraverse[F[_]] extends Traverse[F] with Reducible[F] { self => def nonEmptyTraverse[G[_]: Apply, A, B](fa: F[A])(f: A => G[B]): G[F[B]] /** - * Thread all the G effects through the F structure to invert the - * structure from F[G[A]] to G[F[A]]. + * Thread all the G effects through the F structure to invert the structure from F[G[A]] to G[F[A]]. * * Example: * {{{ @@ -84,8 +82,7 @@ trait NonEmptyTraverse[F[_]] extends Traverse[F] with Reducible[F] { self => G.map(nonEmptyTraverse(fa)(f))(F.flatten) /** - * Thread all the G effects through the F structure and flatten to invert the - * structure from F[G[F[A]]] to G[F[A]]. + * Thread all the G effects through the F structure and flatten to invert the structure from F[G[F[A]]] to G[F[A]]. * * Example: * {{{ diff --git a/core/src/main/scala/cats/NotNull.scala b/core/src/main/scala/cats/NotNull.scala index 137eaff008..a320388659 100644 --- a/core/src/main/scala/cats/NotNull.scala +++ b/core/src/main/scala/cats/NotNull.scala @@ -22,25 +22,22 @@ package cats /** - * An instance of `NotNull[A]` indicates that `A` does not have a static type - * of `Null`. + * An instance of `NotNull[A]` indicates that `A` does not have a static type of `Null`. * - * This can be useful in preventing `Null` from being inferred when a type - * parameter is omitted. + * This can be useful in preventing `Null` from being inferred when a type parameter is omitted. * - * This trait is used along with ambiguous implicits to achieve the goal of - * preventing inference of `Null`. This ambiguous implicit trick has been used - * in the Scala community for some time. [[https://gist.github.com/milessabin/de58f3ba7024d51dcc1a Here]] - * is an early example of such a trick being used in a similar way to prevent a - * `Nothing` type. + * This trait is used along with ambiguous implicits to achieve the goal of preventing inference of `Null`. This + * ambiguous implicit trick has been used in the Scala community for some time. + * [[https://gist.github.com/milessabin/de58f3ba7024d51dcc1a Here]] is an early example of such a trick being used in a + * similar way to prevent a `Nothing` type. */ sealed trait NotNull[A] object NotNull { /** - * Since NotNull is just a marker trait with no functionality, it's safe to - * reuse a single instance of it. This helps prevent unnecessary allocations. + * Since NotNull is just a marker trait with no functionality, it's safe to reuse a single instance of it. This helps + * prevent unnecessary allocations. */ private[this] val singleton: NotNull[Any] = new NotNull[Any] {} diff --git a/core/src/main/scala/cats/Parallel.scala b/core/src/main/scala/cats/Parallel.scala index 48babeae3d..6fa3b7abf9 100644 --- a/core/src/main/scala/cats/Parallel.scala +++ b/core/src/main/scala/cats/Parallel.scala @@ -25,8 +25,8 @@ import cats.arrow.FunctionK import cats.data.{Validated, ZipList, ZipVector} /** - * Some types that form a FlatMap, are also capable of forming an Apply that supports parallel composition. - * The NonEmptyParallel type class allows us to represent this relationship. + * Some types that form a FlatMap, are also capable of forming an Apply that supports parallel composition. The + * NonEmptyParallel type class allows us to represent this relationship. */ trait NonEmptyParallel[M[_]] extends Serializable { type F[_] @@ -52,8 +52,7 @@ trait NonEmptyParallel[M[_]] extends Serializable { def parallel: M ~> F /** - * Like [[Apply.productR]], but uses the apply instance - * corresponding to the Parallel instance instead. + * Like [[Apply.productR]], but uses the apply instance corresponding to the Parallel instance instead. */ def parProductR[A, B](ma: M[A])(mb: M[B]): M[B] = Parallel.parMap2(ma, mb)((_, b) => b)(this) @@ -62,8 +61,7 @@ trait NonEmptyParallel[M[_]] extends Serializable { @inline private[cats] def parFollowedBy[A, B](ma: M[A])(mb: M[B]): M[B] = parProductR(ma)(mb) /** - * Like [[Apply.productL]], but uses the apply instance - * corresponding to the Parallel instance instead. + * Like [[Apply.productL]], but uses the apply instance corresponding to the Parallel instance instead. */ def parProductL[A, B](ma: M[A])(mb: M[B]): M[A] = Parallel.parMap2(ma, mb)((a, _) => a)(this) @@ -74,8 +72,8 @@ trait NonEmptyParallel[M[_]] extends Serializable { } /** - * Some types that form a Monad, are also capable of forming an Applicative that supports parallel composition. - * The Parallel type class allows us to represent this relationship. + * Some types that form a Monad, are also capable of forming an Applicative that supports parallel composition. The + * Parallel type class allows us to represent this relationship. */ trait Parallel[M[_]] extends NonEmptyParallel[M] { @@ -94,10 +92,9 @@ trait Parallel[M[_]] extends NonEmptyParallel[M] { override def flatMap: FlatMap[M] = monad /** - * Provides an `ApplicativeError[F, E]` instance for any F, that has a `Parallel.Aux[M, F]` - * and a `MonadError[M, E]` instance. - * I.e. if you have a type M[_], that supports parallel composition through type F[_], - * then you can get `ApplicativeError[F, E]` from `MonadError[M, E]`. + * Provides an `ApplicativeError[F, E]` instance for any F, that has a `Parallel.Aux[M, F]` and a `MonadError[M, E]` + * instance. I.e. if you have a type M[_], that supports parallel composition through type F[_], then you can get + * `ApplicativeError[F, E]` from `MonadError[M, E]`. */ def applicativeError[E](implicit E: MonadError[M, E]): ApplicativeError[F, E] = new Apply.AbstractApply[F] with ApplicativeError[F, E] { @@ -152,8 +149,8 @@ object Parallel extends ParallelArityFunctions2 { def apply[M[_]](implicit P: Parallel[M], D: DummyImplicit): Parallel.Aux[M, P.F] = P /** - * Like `TraverseFilter#traverseFilter`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `TraverseFilter#traverseFilter`, but uses the applicative instance corresponding to the Parallel instance + * instead. * * Example: * {{{ @@ -177,8 +174,8 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `TraverseFilter#sequenceFilter`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `TraverseFilter#sequenceFilter`, but uses the applicative instance corresponding to the Parallel instance + * instead. * * Example: * {{{ @@ -196,8 +193,7 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `TraverseFilter#filterA`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `TraverseFilter#filterA`, but uses the applicative instance corresponding to the Parallel instance instead. * * Example: * {{{ @@ -220,8 +216,7 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Traverse[A].sequence`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Traverse[A].sequence`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parSequence[T[_]: Traverse, M[_], A](tma: T[M[A]])(implicit P: Parallel[M]): M[T[A]] = { val fta: P.F[T[A]] = Traverse[T].traverse(tma)(P.parallel.apply(_))(using P.applicative) @@ -229,8 +224,7 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Traverse[A].traverse`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Traverse[A].traverse`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parTraverse[T[_]: Traverse, M[_], A, B](ta: T[A])(f: A => M[B])(implicit P: Parallel[M]): M[T[B]] = { val gtb: P.F[T[B]] = Traverse[T].traverse(ta)(a => P.parallel(f(a)))(using P.applicative) @@ -238,8 +232,7 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Traverse[A].flatTraverse`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Traverse[A].flatTraverse`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parFlatTraverse[T[_]: Traverse: FlatMap, M[_], A, B]( ta: T[A] @@ -249,8 +242,7 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Traverse[A].flatSequence`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Traverse[A].flatSequence`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parFlatSequence[T[_]: Traverse: FlatMap, M[_], A]( tma: T[M[T[A]]] @@ -260,8 +252,7 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Foldable[A].sequenceVoid`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Foldable[A].sequenceVoid`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parSequenceVoid[T[_]: Foldable, M[_], A](tma: T[M[A]])(implicit P: Parallel[M]): M[Unit] = { val fu: P.F[Unit] = Foldable[T].traverseVoid(tma)(P.parallel.apply(_))(P.applicative) @@ -271,14 +262,14 @@ object Parallel extends ParallelArityFunctions2 { /** * Alias for `parSequenceVoid`. * - * @deprecated this method should be considered as deprecated and replaced by `parSequenceVoid`. + * @deprecated + * this method should be considered as deprecated and replaced by `parSequenceVoid`. */ def parSequence_[T[_]: Foldable, M[_], A](tma: T[M[A]])(implicit P: Parallel[M]): M[Unit] = parSequenceVoid(tma) /** - * Like `Foldable[A].traverseVoid`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Foldable[A].traverseVoid`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parTraverseVoid[T[_]: Foldable, M[_], A, B](ta: T[A])(f: A => M[B])(implicit P: Parallel[M]): M[Unit] = { val gtb: P.F[Unit] = Foldable[T].traverseVoid(ta)(a => P.parallel(f(a)))(P.applicative) @@ -288,7 +279,8 @@ object Parallel extends ParallelArityFunctions2 { /** * Alias for `parTraverseVoid`. * - * @deprecated this method should be considered as deprecated and replaced by `parTraverseVoid`. + * @deprecated + * this method should be considered as deprecated and replaced by `parTraverseVoid`. */ def parTraverse_[T[_]: Foldable, M[_], A, B](ta: T[A])(f: A => M[B])(implicit P: Parallel[M]): M[Unit] = parTraverseVoid(ta)(f) @@ -314,8 +306,8 @@ object Parallel extends ParallelArityFunctions2 { parUnorderedFlatTraverse[T, M, F, M[T[A]], A](ta)(Predef.identity) /** - * Like `NonEmptyTraverse[A].nonEmptySequence`, but uses the apply instance - * corresponding to the Parallel instance instead. + * Like `NonEmptyTraverse[A].nonEmptySequence`, but uses the apply instance corresponding to the Parallel instance + * instead. */ def parNonEmptySequence[T[_]: NonEmptyTraverse, M[_], A]( tma: T[M[A]] @@ -325,8 +317,8 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `NonEmptyTraverse[A].nonEmptyTraverse`, but uses the apply instance - * corresponding to the Parallel instance instead. + * Like `NonEmptyTraverse[A].nonEmptyTraverse`, but uses the apply instance corresponding to the Parallel instance + * instead. */ def parNonEmptyTraverse[T[_]: NonEmptyTraverse, M[_], A, B]( ta: T[A] @@ -336,8 +328,8 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `NonEmptyTraverse[A].nonEmptyFlatTraverse`, but uses the apply instance - * corresponding to the Parallel instance instead. + * Like `NonEmptyTraverse[A].nonEmptyFlatTraverse`, but uses the apply instance corresponding to the Parallel instance + * instead. */ def parNonEmptyFlatTraverse[T[_]: NonEmptyTraverse: FlatMap, M[_], A, B]( ta: T[A] @@ -348,8 +340,8 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `NonEmptyTraverse[A].nonEmptyFlatSequence`, but uses the apply instance - * corresponding to the Parallel instance instead. + * Like `NonEmptyTraverse[A].nonEmptyFlatSequence`, but uses the apply instance corresponding to the Parallel instance + * instead. */ def parNonEmptyFlatSequence[T[_]: NonEmptyTraverse: FlatMap, M[_], A]( tma: T[M[T[A]]] @@ -359,8 +351,8 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Reducible[A].nonEmptySequenceVoid`, but uses the apply instance - * corresponding to the Parallel instance instead. + * Like `Reducible[A].nonEmptySequenceVoid`, but uses the apply instance corresponding to the Parallel instance + * instead. */ def parNonEmptySequenceVoid[T[_]: Reducible, M[_], A]( tma: T[M[A]] @@ -372,7 +364,8 @@ object Parallel extends ParallelArityFunctions2 { /** * Alias for `parNonEmptySequenceVoid`. * - * @deprecated this method should be considered as deprecated and replaced by `parNonEmptySequenceVoid`. + * @deprecated + * this method should be considered as deprecated and replaced by `parNonEmptySequenceVoid`. */ def parNonEmptySequence_[T[_]: Reducible, M[_], A]( tma: T[M[A]] @@ -380,8 +373,8 @@ object Parallel extends ParallelArityFunctions2 { parNonEmptySequenceVoid[T, M, A](tma) /** - * Like `Reducible[A].nonEmptyTraverseVoid`, but uses the apply instance - * corresponding to the Parallel instance instead. + * Like `Reducible[A].nonEmptyTraverseVoid`, but uses the apply instance corresponding to the Parallel instance + * instead. */ def parNonEmptyTraverseVoid[T[_]: Reducible, M[_], A, B]( ta: T[A] @@ -393,7 +386,8 @@ object Parallel extends ParallelArityFunctions2 { /** * Alias for `parNonEmptyTraverseVoid`. * - * @deprecated this method should be considered as deprecated and replaced by `parNonEmptyTraverseVoid`. + * @deprecated + * this method should be considered as deprecated and replaced by `parNonEmptyTraverseVoid`. */ def parNonEmptyTraverse_[T[_]: Reducible, M[_], A, B]( ta: T[A] @@ -401,8 +395,7 @@ object Parallel extends ParallelArityFunctions2 { parNonEmptyTraverseVoid[T, M, A, B](ta)(f) /** - * Like `Bitraverse[A].bitraverse`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Bitraverse[A].bitraverse`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parBitraverse[T[_, _]: Bitraverse, M[_], A, B, C, D]( tab: T[A, B] @@ -413,8 +406,7 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Bitraverse[A].bisequence`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Bitraverse[A].bisequence`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parBisequence[T[_, _]: Bitraverse, M[_], A, B]( tmamb: T[M[A], M[B]] @@ -425,8 +417,8 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Bitraverse[A].leftTraverse`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Bitraverse[A].leftTraverse`, but uses the applicative instance corresponding to the Parallel instance + * instead. */ def parLeftTraverse[T[_, _]: Bitraverse, M[_], A, B, C]( tab: T[A, B] @@ -437,8 +429,8 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Bitraverse[A].leftSequence`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Bitraverse[A].leftSequence`, but uses the applicative instance corresponding to the Parallel instance + * instead. */ def parLeftSequence[T[_, _]: Bitraverse, M[_], A, B]( tmab: T[M[A], B] @@ -449,8 +441,7 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Foldable[A].foldMapA`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Foldable[A].foldMapA`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parFoldMapA[T[_], M[_], A, B]( ta: T[A] @@ -461,8 +452,8 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Reducible[A].reduceMapA`, but uses the apply instance corresponding - * to the `NonEmptyParallel` instance instead. + * Like `Reducible[A].reduceMapA`, but uses the apply instance corresponding to the `NonEmptyParallel` instance + * instead. */ def parReduceMapA[T[_], M[_], A, B]( ta: T[A] @@ -473,22 +464,19 @@ object Parallel extends ParallelArityFunctions2 { } /** - * Like `Applicative[F].ap`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Applicative[F].ap`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parAp[M[_], A, B](mf: M[A => B])(ma: M[A])(implicit P: NonEmptyParallel[M]): M[B] = P.sequential(P.apply.ap(P.parallel(mf))(P.parallel(ma))) /** - * Like `Applicative[F].product`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Applicative[F].product`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parProduct[M[_], A, B](ma: M[A], mb: M[B])(implicit P: NonEmptyParallel[M]): M[(A, B)] = P.sequential(P.apply.product(P.parallel(ma), P.parallel(mb))) /** - * Like `Applicative[F].ap2`, but uses the applicative instance - * corresponding to the Parallel instance instead. + * Like `Applicative[F].ap2`, but uses the applicative instance corresponding to the Parallel instance instead. */ def parAp2[M[_], A, B, Z](ff: M[(A, B) => Z])(ma: M[A], mb: M[B])(implicit P: NonEmptyParallel[M]): M[Z] = P.sequential( @@ -496,33 +484,29 @@ object Parallel extends ParallelArityFunctions2 { ) /** - * Like `Applicative[F].replicateA`, but uses the apply instance - * corresponding to the Parallel instance instead. + * Like `Applicative[F].replicateA`, but uses the apply instance corresponding to the Parallel instance instead. */ def parReplicateA[M[_], A](n: Int, ma: M[A])(implicit P: Parallel[M]): M[List[A]] = P.sequential(P.applicative.replicateA(n, P.parallel(ma))) /** - * Like `Applicative[F].replicateA_`, but uses the apply instance - * corresponding to the Parallel instance instead. + * Like `Applicative[F].replicateA_`, but uses the apply instance corresponding to the Parallel instance instead. */ def parReplicateA_[M[_], A](n: Int, ma: M[A])(implicit P: Parallel[M]): M[Unit] = P.sequential(P.applicative.replicateA_(n, P.parallel(ma))) /** - * Provides an `ApplicativeError[F, E]` instance for any F, that has a `Parallel.Aux[M, F]` - * and a `MonadError[M, E]` instance. - * I.e. if you have a type M[_], that supports parallel composition through type F[_], - * then you can get `ApplicativeError[F, E]` from `MonadError[M, E]`. + * Provides an `ApplicativeError[F, E]` instance for any F, that has a `Parallel.Aux[M, F]` and a `MonadError[M, E]` + * instance. I.e. if you have a type M[_], that supports parallel composition through type F[_], then you can get + * `ApplicativeError[F, E]` from `MonadError[M, E]`. */ def applicativeError[M[_], E](implicit P: Parallel[M], E: MonadError[M, E]): ApplicativeError[P.F, E] = P.applicativeError[E] /** - * A Parallel instance for any type `M[_]` that supports parallel composition through itself. - * Can also be used for giving `Parallel` instances to types that do not support parallel composition, - * but are required to have an instance of `Parallel` defined, - * in which case parallel composition will actually be sequential. + * A Parallel instance for any type `M[_]` that supports parallel composition through itself. Can also be used for + * giving `Parallel` instances to types that do not support parallel composition, but are required to have an instance + * of `Parallel` defined, in which case parallel composition will actually be sequential. */ def identity[M[_]: Monad]: Parallel.Aux[M, M] = new Parallel[M] { diff --git a/core/src/main/scala/cats/Reducible.scala b/core/src/main/scala/cats/Reducible.scala index a51ba629b2..3ebd5029a3 100644 --- a/core/src/main/scala/cats/Reducible.scala +++ b/core/src/main/scala/cats/Reducible.scala @@ -26,15 +26,13 @@ import cats.data.{Ior, NonEmptyList} /** * Data structures that can be reduced to a summary value. * - * `Reducible` is like a non-empty `Foldable`. In addition to the fold - * methods it provides reduce methods which do not require an initial - * value. + * `Reducible` is like a non-empty `Foldable`. In addition to the fold methods it provides reduce methods which do not + * require an initial value. * - * In addition to the methods needed by `Foldable`, `Reducible` is - * implemented in terms of two methods: + * In addition to the methods needed by `Foldable`, `Reducible` is implemented in terms of two methods: * - * - `reduceLeftTo(fa)(f)(g)` eagerly reduces with an additional mapping function - * - `reduceRightTo(fa)(f)(g)` lazily reduces with an additional mapping function + * - `reduceLeftTo(fa)(f)(g)` eagerly reduces with an additional mapping function + * - `reduceRightTo(fa)(f)(g)` lazily reduces with an additional mapping function */ trait Reducible[F[_]] extends Foldable[F] { self => @@ -59,8 +57,7 @@ trait Reducible[F[_]] extends Foldable[F] { self => reduceLeft(fa)(A.combine) /** - * Reduce a `F[G[A]]` value using `SemigroupK[G]`, a universal - * semigroup for `G[_]`. + * Reduce a `F[G[A]]` value using `SemigroupK[G]`, a universal semigroup for `G[_]`. * * This method is a generalization of `reduce`. * @@ -75,8 +72,7 @@ trait Reducible[F[_]] extends Foldable[F] { self => reduce(fga)(G.algebra) /** - * Apply `f` to each element of `fa` and combine them using the - * given `Semigroup[B]`. + * Apply `f` to each element of `fa` and combine them using the given `Semigroup[B]`. * * {{{ * scala> import cats.Reducible @@ -93,8 +89,7 @@ trait Reducible[F[_]] extends Foldable[F] { self => reduceLeftTo(fa)(f)((b, a) => B.combine(b, f(a))) /** - * Apply `f` to each element of `fa` and combine them using the - * given `SemigroupK[G]`. + * Apply `f` to each element of `fa` and combine them using the given `SemigroupK[G]`. * * {{{ * scala> import cats._, cats.data._ @@ -109,8 +104,7 @@ trait Reducible[F[_]] extends Foldable[F] { self => reduceLeftTo(fa)(f)((b, a) => G.combineK(b, f(a))) /** - * Apply `f` to the "initial element" of `fa` and combine it with - * every other value using the given function `g`. + * Apply `f` to the "initial element" of `fa` and combine it with every other value using the given function `g`. */ def reduceLeftTo[A, B](fa: F[A])(f: A => B)(g: (B, A) => B): B @@ -121,8 +115,7 @@ trait Reducible[F[_]] extends Foldable[F] { self => reduceLeftTo(fa)(f)((gb, a) => G.flatMap(gb)(g(_, a))) /** - * Reduce a `F[G[A]]` value using `Applicative[G]` and `Semigroup[A]`, a universal - * semigroup for `G[_]`. + * Reduce a `F[G[A]]` value using `Applicative[G]` and `Semigroup[A]`, a universal semigroup for `G[_]`. * * This method is similar to [[reduce]], but may short-circuit. */ @@ -130,8 +123,8 @@ trait Reducible[F[_]] extends Foldable[F] { self => reduceMapA(fga)(identity) /** - * Reduce in an [[Apply]] context by mapping the `A` values to `G[B]`. combining - * the `B` values using the given `Semigroup[B]` instance. + * Reduce in an [[Apply]] context by mapping the `A` values to `G[B]`. combining the `B` values using the given + * `Semigroup[B]` instance. * * Similar to [[reduceMapM]], but may be less efficient. * @@ -154,8 +147,8 @@ trait Reducible[F[_]] extends Foldable[F] { self => reduceRightTo(fa)(f)((a, egb) => G.map2Eval(f(a), egb)(B.combine)).value /** - * Reduce in an [[FlatMap]] context by mapping the `A` values to `G[B]`. combining - * the `B` values using the given `Semigroup[B]` instance. + * Reduce in an [[FlatMap]] context by mapping the `A` values to `G[B]`. combining the `B` values using the given + * `Semigroup[B]` instance. * * Similar to [[reduceLeftM]], but using a `Semigroup[B]`. May be more efficient than [[reduceMapA]]. * @@ -184,8 +177,8 @@ trait Reducible[F[_]] extends Foldable[F] { self => Some(reduceLeftTo(fa)(f)(g)) /** - * Apply `f` to the "initial element" of `fa` and lazily combine it - * with every other value using the given function `g`. + * Apply `f` to the "initial element" of `fa` and lazily combine it with every other value using the given function + * `g`. */ def reduceRightTo[A, B](fa: F[A])(f: A => B)(g: (A, Eval[B]) => Eval[B]): Eval[B] @@ -198,19 +191,15 @@ trait Reducible[F[_]] extends Foldable[F] { self => /** * Traverse `F[A]` using `Apply[G]`. * - * `A` values will be mapped into `G[B]` and combined using - * `Apply#map2`. + * `A` values will be mapped into `G[B]` and combined using `Apply#map2`. * - * This method is similar to [[Foldable.traverseVoid]]. There are two - * main differences: + * This method is similar to [[Foldable.traverseVoid]]. There are two main differences: * - * 1. We only need an [[Apply]] instance for `G` here, since we - * don't need to call [[Applicative.pure]] for a starting value. - * 2. This performs a strict left-associative traversal and thus - * must always traverse the entire data structure. Prefer - * [[Foldable.traverseVoid]] if you have an [[Applicative]] instance - * available for `G` and want to take advantage of short-circuiting - * the traversal. + * 1. We only need an [[Apply]] instance for `G` here, since we don't need to call [[Applicative.pure]] for a + * starting value. + * 2. This performs a strict left-associative traversal and thus must always traverse the entire data structure. + * Prefer [[Foldable.traverseVoid]] if you have an [[Applicative]] instance available for `G` and want to take + * advantage of short-circuiting the traversal. */ def nonEmptyTraverseVoid[G[_], A, B](fa: F[A])(f: A => G[B])(implicit G: Apply[G]): G[Unit] = { val f1 = f.andThen(G.void) @@ -220,7 +209,8 @@ trait Reducible[F[_]] extends Foldable[F] { self => /** * Alias for `nonEmptyTraverseVoid`. * - * @deprecated this method should be considered as deprecated and replaced by `nonEmptyTraverseVoid`. + * @deprecated + * this method should be considered as deprecated and replaced by `nonEmptyTraverseVoid`. */ def nonEmptyTraverse_[G[_], A, B](fa: F[A])(f: A => G[B])(implicit G: Apply[G]): G[Unit] = nonEmptyTraverseVoid(fa)(f) @@ -228,9 +218,8 @@ trait Reducible[F[_]] extends Foldable[F] { self => /** * Sequence `F[G[A]]` using `Apply[G]`. * - * This method is similar to [[Foldable.sequenceVoid]] but requires only - * an [[Apply]] instance for `G` instead of [[Applicative]]. See the - * [[nonEmptyTraverseVoid]] documentation for a description of the differences. + * This method is similar to [[Foldable.sequenceVoid]] but requires only an [[Apply]] instance for `G` instead of + * [[Applicative]]. See the [[nonEmptyTraverseVoid]] documentation for a description of the differences. */ def nonEmptySequenceVoid[G[_], A](fga: F[G[A]])(implicit G: Apply[G]): G[Unit] = nonEmptyTraverseVoid(fga)(identity) @@ -238,7 +227,8 @@ trait Reducible[F[_]] extends Foldable[F] { self => /** * Alias for `nonEmptySequenceVoid`. * - * @deprecated this method should be considered as deprecated and replaced by `nonEmptySequenceVoid`. + * @deprecated + * this method should be considered as deprecated and replaced by `nonEmptySequenceVoid`. */ def nonEmptySequence_[G[_], A](fga: F[G[A]])(implicit G: Apply[G]): G[Unit] = nonEmptySequenceVoid(fga) @@ -263,7 +253,8 @@ trait Reducible[F[_]] extends Foldable[F] { self => /** * Find the minimum `A` item in this structure according to an `Order.by(f)`. * - * @see [[maximumBy]] for maximum instead of minimum. + * @see + * [[maximumBy]] for maximum instead of minimum. */ def minimumBy[A, B: Order](fa: F[A])(f: A => B): A = minimum(fa)(Order.by(f)) @@ -271,16 +262,18 @@ trait Reducible[F[_]] extends Foldable[F] { self => /** * Find the maximum `A` item in this structure according to an `Order.by(f)`. * - * @see [[minimumBy]] for minimum instead of maximum. + * @see + * [[minimumBy]] for minimum instead of maximum. */ def maximumBy[A, B: Order](fa: F[A])(f: A => B): A = maximum(fa)(Order.by(f)) /** - * Find all the minimum `A` items in this structure. - * For all elements in the result Order.eqv(x, y) is true. Preserves order. + * Find all the minimum `A` items in this structure. For all elements in the result Order.eqv(x, y) is true. Preserves + * order. * - * @see [[maximumNel]] for maximum instead of minimum. + * @see + * [[maximumNel]] for maximum instead of minimum. */ def minimumNel[A](fa: F[A])(implicit A: Order[A]): NonEmptyList[A] = reduceLeftTo(fa)(NonEmptyList.one) { @@ -290,10 +283,11 @@ trait Reducible[F[_]] extends Foldable[F] { self => }.reverse /** - * Find all the maximum `A` items in this structure. - * For all elements in the result Order.eqv(x, y) is true. Preserves order. + * Find all the maximum `A` items in this structure. For all elements in the result Order.eqv(x, y) is true. Preserves + * order. * - * @see [[minimumNel]] for minimum instead of maximum. + * @see + * [[minimumNel]] for minimum instead of maximum. */ def maximumNel[A](fa: F[A])(implicit A: Order[A]): NonEmptyList[A] = reduceLeftTo(fa)(NonEmptyList.one) { @@ -303,19 +297,21 @@ trait Reducible[F[_]] extends Foldable[F] { self => }.reverse /** - * Find all the minimum `A` items in this structure according to an `Order.by(f)`. - * For all elements in the result Order.eqv(x, y) is true. Preserves order. + * Find all the minimum `A` items in this structure according to an `Order.by(f)`. For all elements in the result + * Order.eqv(x, y) is true. Preserves order. * - * @see [[maximumByNel]] for maximum instead of minimum. + * @see + * [[maximumByNel]] for maximum instead of minimum. */ def minimumByNel[A, B: Order](fa: F[A])(f: A => B): NonEmptyList[A] = minimumNel(fa)(Order.by(f)) /** - * Find all the maximum `A` items in this structure according to an `Order.by(f)`. - * For all elements in the result Order.eqv(x, y) is true. Preserves order. + * Find all the maximum `A` items in this structure according to an `Order.by(f)`. For all elements in the result + * Order.eqv(x, y) is true. Preserves order. * - * @see [[minimumByNel]] for minimum instead of maximum. + * @see + * [[minimumByNel]] for minimum instead of maximum. */ def maximumByNel[A, B: Order](fa: F[A])(f: A => B): NonEmptyList[A] = maximumNel(fa)(Order.by(f)) diff --git a/core/src/main/scala/cats/Representable.scala b/core/src/main/scala/cats/Representable.scala index 1d073f8c1f..13c006a472 100644 --- a/core/src/main/scala/cats/Representable.scala +++ b/core/src/main/scala/cats/Representable.scala @@ -26,10 +26,9 @@ package cats * * Is a witness to the isomorphism forall A. F[A] <-> Representation => A * - * Must obey the laws defined in cats.laws.RepresentableLaws - * i.e. - * tabulate andThen index = identity - * index andThen tabulate = identity + * Must obey the laws defined in `cats.laws.RepresentableLaws` , i.e. + * - tabulate andThen index = identity + * - index andThen tabulate = identity * * Inspired by the Haskell representable package * http://hackage.haskell.org/package/representable-functors-3.2.0.2/docs/Data-Functor-Representable.html @@ -173,8 +172,7 @@ object Representable { } /** - * Derives a `Bimonad` instance for any `Representable` functor whose representation - * has a `Monoid` instance. + * Derives a `Bimonad` instance for any `Representable` functor whose representation has a `Monoid` instance. */ def bimonad[F[_], R](implicit Rep: Representable.Aux[F, R], Mon: Monoid[R]): Bimonad[F] = new RepresentableBimonad[F, R] { diff --git a/core/src/main/scala/cats/SemigroupK.scala b/core/src/main/scala/cats/SemigroupK.scala index 88bada7351..501c0c7ac1 100644 --- a/core/src/main/scala/cats/SemigroupK.scala +++ b/core/src/main/scala/cats/SemigroupK.scala @@ -30,20 +30,16 @@ import cats.kernel.compat.scalaVersionSpecific.* /** * SemigroupK is a universal semigroup which operates on kinds. * - * This type class is useful when its type parameter F[_] has a - * structure that can be combined for any particular type. Thus, - * SemigroupK is like a Semigroup for kinds (i.e. parametrized - * types). + * This type class is useful when its type parameter F[_] has a structure that can be combined for any particular type. + * Thus, SemigroupK is like a Semigroup for kinds (i.e. parametrized types). * * A SemigroupK[F] can produce a Semigroup[F[A]] for any type A. * * Here's how to distinguish Semigroup and SemigroupK: * - * - Semigroup[A] allows two A values to be combined. - * - * - SemigroupK[F] allows two F[A] values to be combined, for any A. - * The combination operation just depends on the structure of F, - * but not the structure of A. + * - Semigroup[A] allows two A values to be combined. + * - SemigroupK[F] allows two F[A] values to be combined, for any A. The combination operation just depends on the + * structure of F, but not the structure of A. */ trait SemigroupK[F[_]] extends Serializable { self => @@ -61,16 +57,14 @@ trait SemigroupK[F[_]] extends Serializable { self => def combineK[A](x: F[A], y: F[A]): F[A] /** - * Similar to [[combineK]] but uses [[Eval]] to allow for laziness in the second - * argument. This can allow for "short-circuiting" of computations. + * Similar to [[combineK]] but uses [[Eval]] to allow for laziness in the second argument. This can allow for + * "short-circuiting" of computations. * - * NOTE: the default implementation of `combineKEval` does not short-circuit - * computations. For data structures that can benefit from laziness, [[SemigroupK]] - * instances should override this method. + * NOTE: the default implementation of `combineKEval` does not short-circuit computations. For data structures that + * can benefit from laziness, [[SemigroupK]] instances should override this method. * - * In the following example, `x.combineK(bomb)` would result in an error, - * but `combineKEval` "short-circuits" the computation. `x` is `Some` and thus the - * result of `bomb` doesn't even need to be evaluated in order to determine + * In the following example, `x.combineK(bomb)` would result in an error, but `combineKEval` "short-circuits" the + * computation. `x` is `Some` and thus the result of `bomb` doesn't even need to be evaluated in order to determine * that the result of `combineKEval` should be `x`. * * {{{ @@ -97,9 +91,8 @@ trait SemigroupK[F[_]] extends Serializable { self => def algebra[A]: Semigroup[F[A]] = combineK(_, _) /** - * "Compose" with a `G[_]` type to form a `SemigroupK` for `λ[α => F[G[α]]]`. - * Note that this universally works for any `G`, because the "inner" structure - * isn't considered when combining two instances. + * "Compose" with a `G[_]` type to form a `SemigroupK` for `λ[α => F[G[α]]]`. Note that this universally works for any + * `G`, because the "inner" structure isn't considered when combining two instances. * * Example: * {{{ @@ -174,8 +167,7 @@ trait SemigroupK[F[_]] extends Serializable { self => as.iterator.reduceOption(combineK[A]) /** - * return a semigroupK that reverses the order - * so combineK(a, b) == reverse.combineK(b, a) + * return a semigroupK that reverses the order so combineK(a, b) == reverse.combineK(b, a) */ def reverse: SemigroupK[F] = new SemigroupK[F] { diff --git a/core/src/main/scala/cats/Semigroupal.scala b/core/src/main/scala/cats/Semigroupal.scala index 246175bff7..c73bd32337 100644 --- a/core/src/main/scala/cats/Semigroupal.scala +++ b/core/src/main/scala/cats/Semigroupal.scala @@ -27,14 +27,13 @@ import scala.concurrent.{ExecutionContext, Future} import scala.util.Try /** - * [[Semigroupal]] captures the idea of composing independent effectful values. - * It is of particular interest when taken together with [[Functor]] - where [[Functor]] - * captures the idea of applying a unary pure function to an effectful value, - * calling `product` with `map` allows one to apply a function of arbitrary arity to multiple - * independent effectful values. + * [[Semigroupal]] captures the idea of composing independent effectful values. It is of particular interest when taken + * together with [[Functor]] - where [[Functor]] captures the idea of applying a unary pure function to an effectful + * value, calling `product` with `map` allows one to apply a function of arbitrary arity to multiple independent + * effectful values. * - * That same idea is also manifested in the form of [[Apply]], and indeed [[Apply]] extends both - * [[Semigroupal]] and [[Functor]] to illustrate this. + * That same idea is also manifested in the form of [[Apply]], and indeed [[Apply]] extends both [[Semigroupal]] and + * [[Functor]] to illustrate this. */ trait Semigroupal[F[_]] extends Serializable { @@ -73,12 +72,13 @@ object Semigroupal extends SemigroupalArityFunctions with ScalaVersionSpecificSe /** * @deprecated - * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone - * (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). - * We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]]. - * However, at this time there are no plans to remove these instances from Cats. + * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone (particularly the semantics of + * [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). We recommend using + * [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of + * [[scala.concurrent.Future Future]]. However, at this time there are no plans to remove these instances from Cats. * - * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] + * @see + * [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] */ implicit def catsSemigroupalForFuture(implicit ec: ExecutionContext): Semigroupal[Future] = cats.instances.future.catsStdInstancesForFuture(ec) diff --git a/core/src/main/scala/cats/Show.scala b/core/src/main/scala/cats/Show.scala index 6491effb7e..68daa9992d 100644 --- a/core/src/main/scala/cats/Show.scala +++ b/core/src/main/scala/cats/Show.scala @@ -27,11 +27,9 @@ import scala.concurrent.duration.{Duration, FiniteDuration} import scala.util.Try /** - * A type class to provide textual representation. It is meant to be a - * better "toString". Whereas toString exists for any Object, - * regardless of whether or not the creator of the class explicitly - * made a toString method, a Show instance will only exist if someone - * explicitly provided one. + * A type class to provide textual representation. It is meant to be a better "toString". Whereas toString exists for + * any Object, regardless of whether or not the creator of the class explicitly made a toString method, a Show instance + * will only exist if someone explicitly provided one. */ trait Show[T] extends Show.ContravariantShow[T] diff --git a/core/src/main/scala/cats/StackSafeMonad.scala b/core/src/main/scala/cats/StackSafeMonad.scala index c7abf74a15..6c4a92022d 100644 --- a/core/src/main/scala/cats/StackSafeMonad.scala +++ b/core/src/main/scala/cats/StackSafeMonad.scala @@ -24,12 +24,11 @@ package cats import scala.util.{Either, Left, Right} /** - * A mix-in for inheriting tailRecM on monads which define a stack-safe flatMap. This is - * ''not'' an appropriate trait to use unless you are 100% certain your monad is stack-safe - * by definition! If your monad is not stack-safe, then the tailRecM implementation you - * will inherit will not be sound, and will result in unexpected stack overflows. This - * trait is only provided because a large number of monads ''do'' define a stack-safe - * flatMap, and so this particular implementation was being repeated over and over again. + * A mix-in for inheriting tailRecM on monads which define a stack-safe flatMap. This is ''not'' an appropriate trait to + * use unless you are 100% certain your monad is stack-safe by definition! If your monad is not stack-safe, then the + * tailRecM implementation you will inherit will not be sound, and will result in unexpected stack overflows. This trait + * is only provided because a large number of monads ''do'' define a stack-safe flatMap, and so this particular + * implementation was being repeated over and over again. */ trait StackSafeMonad[F[_]] extends Monad[F] { diff --git a/core/src/main/scala/cats/Traverse.scala b/core/src/main/scala/cats/Traverse.scala index ff756e4e92..bac2f8e119 100644 --- a/core/src/main/scala/cats/Traverse.scala +++ b/core/src/main/scala/cats/Traverse.scala @@ -31,18 +31,16 @@ import cats.kernel.compat.scalaVersionSpecific.* * * Traversal over a structure with an effect. * - * Traversing with the [[cats.Id]] effect is equivalent to [[cats.Functor]]#map. - * Traversing with the [[cats.data.Const]] effect where the first type parameter has - * a [[cats.Monoid]] instance is equivalent to [[cats.Foldable]]#fold. + * Traversing with the [[cats.Id]] effect is equivalent to [[cats.Functor]]#map. Traversing with the [[cats.data.Const]] + * effect where the first type parameter has a [[cats.Monoid]] instance is equivalent to [[cats.Foldable]]#fold. * * See: [[https://www.cs.ox.ac.uk/jeremy.gibbons/publications/iterator.pdf The Essence of the Iterator Pattern]] */ trait Traverse[F[_]] extends Functor[F] with Foldable[F] with UnorderedTraverse[F] { self => /** - * Given a function which returns a G effect, thread this effect - * through the running of this function on all the values in F, - * returning an F[B] in a G context. + * Given a function which returns a G effect, thread this effect through the running of this function on all the + * values in F, returning an F[B] in a G context. * * Example: * {{{ @@ -57,10 +55,8 @@ trait Traverse[F[_]] extends Functor[F] with Foldable[F] with UnorderedTraverse[ def traverse[G[_]: Applicative, A, B](fa: F[A])(f: A => G[B]): G[F[B]] /** - * Given a function which returns a G effect, thread this effect - * through the running of this function on all the values in F, - * returning an F[A] in a G context, ignoring the values - * returned by provided function. + * Given a function which returns a G effect, thread this effect through the running of this function on all the + * values in F, returning an F[A] in a G context, ignoring the values returned by provided function. * * Example: * {{{ @@ -91,8 +87,7 @@ trait Traverse[F[_]] extends Functor[F] with Foldable[F] with UnorderedTraverse[ G.map(traverse(fa)(f))(F.flatten) /** - * Thread all the G effects through the F structure to invert the - * structure from F[G[A]] to G[F[A]]. + * Thread all the G effects through the F structure to invert the structure from F[G[A]] to G[F[A]]. * * Example: * {{{ @@ -109,8 +104,7 @@ trait Traverse[F[_]] extends Functor[F] with Foldable[F] with UnorderedTraverse[ traverse(fga)(ga => ga) /** - * Thread all the G effects through the F structure and flatten to invert the - * structure from F[G[F[A]]] to G[F[A]]. + * Thread all the G effects through the F structure and flatten to invert the structure from F[G[F[A]]] to G[F[A]]. * * Example: * {{{ @@ -136,65 +130,57 @@ trait Traverse[F[_]] extends Functor[F] with Foldable[F] with UnorderedTraverse[ traverse[Id, A, B](fa)(f) /** - * Akin to [[map]], but allows to keep track of a state value - * when calling the function. + * Akin to [[map]], but allows to keep track of a state value when calling the function. */ def mapAccumulate[S, A, B](init: S, fa: F[A])(f: (S, A) => (S, B)): (S, F[B]) = traverse(fa)(a => State(s => f(s, a))).run(init).value /** - * Akin to [[map]], but also provides the value's index in structure - * F when calling the function. + * Akin to [[map]], but also provides the value's index in structure F when calling the function. */ def mapWithIndex[A, B](fa: F[A])(f: (A, Int) => B): F[B] = mapAccumulate(0, fa)((i, a) => (i + 1) -> f(a, i))._2 /** - * Akin to [[traverse]], but also provides the value's index in - * structure F when calling the function. + * Akin to [[traverse]], but also provides the value's index in structure F when calling the function. * - * This performs the traversal in a single pass but requires that - * effect G is monadic. An applicative traversal can be performed in - * two passes using [[zipWithIndex]] followed by [[traverse]]. + * This performs the traversal in a single pass but requires that effect G is monadic. An applicative traversal can be + * performed in two passes using [[zipWithIndex]] followed by [[traverse]]. */ def traverseWithIndexM[G[_], A, B](fa: F[A])(f: (A, Int) => G[B])(implicit G: Monad[G]): G[F[B]] = traverse(fa)(a => StateT((s: Int) => G.map(f(a, s))(b => (s + 1, b)))).runA(0) /** - * Traverses through the structure F, pairing the values with - * assigned indices. + * Traverses through the structure F, pairing the values with assigned indices. * - * The behavior is consistent with the Scala collection library's - * `zipWithIndex` for collections such as `List`. + * The behavior is consistent with the Scala collection library's `zipWithIndex` for collections such as `List`. */ def zipWithIndex[A](fa: F[A]): F[(A, Int)] = mapWithIndex(fa)((a, i) => (a, i)) /** - * Same as [[traverseWithIndexM]] but the index type is [[Long]] instead of [[Int]]. - */ + * Same as [[traverseWithIndexM]] but the index type is [[Long]] instead of [[Int]]. + */ def traverseWithLongIndexM[G[_], A, B](fa: F[A])(f: (A, Long) => G[B])(implicit G: Monad[G]): G[F[B]] = traverse(fa)(a => StateT((s: Long) => G.map(f(a, s))(b => (s + 1, b)))).runA(0L) /** - * Same as [[mapWithIndex]] but the index type is [[Long]] instead of [[Int]]. - */ + * Same as [[mapWithIndex]] but the index type is [[Long]] instead of [[Int]]. + */ def mapWithLongIndex[A, B](fa: F[A])(f: (A, Long) => B): F[B] = traverseWithLongIndexM[cats.Id, A, B](fa)((a, long) => f(a, long)) /** - * Same as [[zipWithIndex]] but the index type is [[Long]] instead of [[Int]]. - */ + * Same as [[zipWithIndex]] but the index type is [[Long]] instead of [[Int]]. + */ def zipWithLongIndex[A](fa: F[A]): F[(A, Long)] = mapWithLongIndex(fa)((a, long) => (a, long)) /** - * If `fa` contains the element at index `idx`, - * return the copy of `fa` where the element at `idx` is replaced with `b`. - * If there is no element with such an index, return `None`. + * If `fa` contains the element at index `idx`, return the copy of `fa` where the element at `idx` is replaced with + * `b`. If there is no element with such an index, return `None`. * - * The behavior is consistent with the Scala collection library's - * `updated` for collections such as `List`. + * The behavior is consistent with the Scala collection library's `updated` for collections such as `List`. */ def updated_[A, B >: A](fa: F[A], idx: Long, b: B): Option[F[B]] = { if (idx < 0L) diff --git a/core/src/main/scala/cats/TraverseFilter.scala b/core/src/main/scala/cats/TraverseFilter.scala index db655db066..f9a5945afe 100644 --- a/core/src/main/scala/cats/TraverseFilter.scala +++ b/core/src/main/scala/cats/TraverseFilter.scala @@ -27,11 +27,11 @@ import cats.kernel.compat.scalaVersionSpecific.* import scala.collection.immutable.{IntMap, TreeSet} /** - * `TraverseFilter`, also known as `Witherable`, represents list-like structures - * that can essentially have a `traverse` and a `filter` applied as a single - * combined operation (`traverseFilter`). + * `TraverseFilter`, also known as `Witherable`, represents list-like structures that can essentially have a `traverse` + * and a `filter` applied as a single combined operation (`traverseFilter`). * - * Based on Haskell's [[https://hackage.haskell.org/package/witherable-0.1.3.3/docs/Data-Witherable.html Data.Witherable]] + * Based on Haskell's + * [[https://hackage.haskell.org/package/witherable-0.1.3.3/docs/Data-Witherable.html Data.Witherable]] */ trait TraverseFilter[F[_]] extends FunctorFilter[F] { @@ -40,9 +40,8 @@ trait TraverseFilter[F[_]] extends FunctorFilter[F] { final override def functor: Functor[F] = traverse /** - * A combined [[traverse]] and [[filter]]. Filtering is handled via `Option` - * instead of `Boolean` such that the output type `B` can be different than - * the input type `A`. + * A combined [[traverse]] and [[filter]]. Filtering is handled via `Option` instead of `Boolean` such that the output + * type `B` can be different than the input type `A`. * * Example: * {{{ @@ -59,7 +58,7 @@ trait TraverseFilter[F[_]] extends FunctorFilter[F] { /** * A combined [[traverse]] and [[collect]]. - * + * {{{ * scala> import cats.syntax.all._ * scala> val m: Map[Int, String] = Map(1 -> "one", 2 -> "two") * scala> val l: List[Int] = List(1, 2, 3, 4) @@ -67,6 +66,7 @@ trait TraverseFilter[F[_]] extends FunctorFilter[F] { * scala> val result: Eval[List[Option[String]]] = l.traverseCollect(asString) * scala> result.value * res0: List[Option[String]] = List(Some(two), None) + * }}} */ def traverseCollect[G[_], A, B](fa: F[A])(f: PartialFunction[A, G[B]])(implicit G: Applicative[G]): G[F[B]] = { val optF = f.lift @@ -88,8 +88,10 @@ trait TraverseFilter[F[_]] extends FunctorFilter[F] { /** * Filter values inside a `G` context. * - * This is a generalized version of Haskell's [[http://hackage.haskell.org/package/base-4.9.0.0/docs/Control-Monad.html#v:filterM filterM]]. - * [[http://stackoverflow.com/questions/28872396/haskells-filterm-with-filterm-x-true-false-1-2-3 This StackOverflow question]] about `filterM` may be helpful in understanding how it behaves. + * This is a generalized version of Haskell's + * [[http://hackage.haskell.org/package/base-4.9.0.0/docs/Control-Monad.html#v:filterM filterM]]. + * [[http://stackoverflow.com/questions/28872396/haskells-filterm-with-filterm-x-true-false-1-2-3 This StackOverflow question]] + * about `filterM` may be helpful in understanding how it behaves. * * Example: * {{{ @@ -108,7 +110,8 @@ trait TraverseFilter[F[_]] extends FunctorFilter[F] { traverseFilter(fa)(a => G.map(f(a))(if (_) Some(a) else None)) /** - * Like [[traverseFilter]], but uses `Either` instead of `Option` and allows for an action to be run on each filtered value. + * Like [[traverseFilter]], but uses `Either` instead of `Option` and allows for an action to be run on each filtered + * value. */ def traverseEither[G[_], A, B, E]( fa: F[A] @@ -138,8 +141,8 @@ trait TraverseFilter[F[_]] extends FunctorFilter[F] { } /** - * Removes duplicate elements from a list, keeping only the first occurrence. - * This is usually faster than ordDistinct, especially for things that have a slow comparison (like String). + * Removes duplicate elements from a list, keeping only the first occurrence. This is usually faster than ordDistinct, + * especially for things that have a slow comparison (like String). */ def hashDistinct[A](fa: F[A])(implicit H: Hash[A]): F[A] = traverseFilter(fa) { a => diff --git a/core/src/main/scala/cats/UnorderedFoldable.scala b/core/src/main/scala/cats/UnorderedFoldable.scala index 09ee27b4c6..c2019ec204 100644 --- a/core/src/main/scala/cats/UnorderedFoldable.scala +++ b/core/src/main/scala/cats/UnorderedFoldable.scala @@ -36,8 +36,8 @@ trait UnorderedFoldable[F[_]] extends Serializable { unorderedFoldMap(fa)(identity) /** - * Fold in a [[CommutativeApplicative]] context by mapping the `A` values to `G[B]`. combining - * the `B` values using the given `CommutativeMonoid[B]` instance. + * Fold in a [[CommutativeApplicative]] context by mapping the `A` values to `G[B]`, combining the `B` values using + * the given `CommutativeMonoid[B]` instance. * * {{{ * scala> import cats.UnorderedFoldable @@ -90,8 +90,7 @@ trait UnorderedFoldable[F[_]] extends Serializable { /** * The size of this UnorderedFoldable. * - * This is overridden in structures that have more efficient size implementations - * (e.g. Vector, Set, Map). + * This is overridden in structures that have more efficient size implementations (e.g. `Vector`, `Set`, `Map`). * * Note: will not terminate for infinite-sized collections. */ diff --git a/core/src/main/scala/cats/arrow/Arrow.scala b/core/src/main/scala/cats/arrow/Arrow.scala index 0d041f4074..09c9a395e3 100644 --- a/core/src/main/scala/cats/arrow/Arrow.scala +++ b/core/src/main/scala/cats/arrow/Arrow.scala @@ -28,10 +28,10 @@ package arrow trait Arrow[F[_, _]] extends Category[F] with Strong[F] { self => /** - * Lift a function into the context of an Arrow. + * Lift a function into the context of an Arrow. * - * In the reference articles "Arrows are Promiscuous...", and in the corresponding Haskell - * library `Control.Arrow`, this function is called `arr`. + * In the reference articles "Arrows are Promiscuous...", and in the corresponding Haskell library `Control.Arrow`, + * this function is called `arr`. */ def lift[A, B](f: A => B): F[A, B] @@ -47,8 +47,7 @@ trait Arrow[F[_, _]] extends Category[F] with Strong[F] { self => } /** - * Create a new computation `F` that splits its input between `f` and `g` - * and combines the output of each. + * Create a new computation `F` that splits its input between `f` and `g` and combines the output of each. * * Example: * {{{ @@ -61,8 +60,8 @@ trait Arrow[F[_, _]] extends Category[F] with Strong[F] { self => * res0: (Long, Double) = (3,4.0) * }}} * - * Note that the arrow laws do not guarantee the non-interference between the _effects_ of - * `f` and `g` in the context of F. This means that `f *** g` may not be equivalent to `g *** f`. + * Note that the arrow laws do not guarantee the non-interference between the _effects_ of `f` and `g` in the context + * of F. This means that `f *** g` may not be equivalent to `g *** f`. */ def split[A, B, C, D](f: F[A, B], g: F[C, D]): F[(A, C), (B, D)] = @@ -81,8 +80,8 @@ trait Arrow[F[_, _]] extends Category[F] with Strong[F] { self => * res0: (Int, Double) = (1,1.0) * }}} * - * Note that the arrow laws do not guarantee the non-interference between the _effects_ of - * `f` and `g` in the context of F. This means that `f &&& g` may not be equivalent to `g &&& f`. + * Note that the arrow laws do not guarantee the non-interference between the _effects_ of `f` and `g` in the context + * of F. This means that `f &&& g` may not be equivalent to `g &&& f`. */ def merge[A, B, C](f: F[A, B], g: F[A, C]): F[A, (B, C)] = diff --git a/core/src/main/scala/cats/arrow/ArrowChoice.scala b/core/src/main/scala/cats/arrow/ArrowChoice.scala index c76745e9ac..0d04c93380 100644 --- a/core/src/main/scala/cats/arrow/ArrowChoice.scala +++ b/core/src/main/scala/cats/arrow/ArrowChoice.scala @@ -28,13 +28,10 @@ package arrow trait ArrowChoice[F[_, _]] extends Arrow[F] with Choice[F] { self => /** - * ArrowChoice yields Arrows with choice, allowing distribution - * over coproducts. + * ArrowChoice yields Arrows with choice, allowing distribution over coproducts. * - * Given two `F`s (`f` and `g`), create a new `F` with - * domain the coproduct of the domains of `f` and `g`, - * and codomain the coproduct of the codomains of `f` and `g`. - * This is the sum notion to `split`'s product. + * Given two `F`s (`f` and `g`), create a new `F` with domain the coproduct of the domains of `f` and `g`, and + * codomain the coproduct of the codomains of `f` and `g`. This is the sum notion to `split`'s product. * * Example: * {{{ diff --git a/core/src/main/scala/cats/arrow/Choice.scala b/core/src/main/scala/cats/arrow/Choice.scala index d5259456d2..a74bf98f20 100644 --- a/core/src/main/scala/cats/arrow/Choice.scala +++ b/core/src/main/scala/cats/arrow/Choice.scala @@ -25,9 +25,8 @@ package arrow trait Choice[F[_, _]] extends Category[F] { /** - * Given two `F`s (`f` and `g`) with a common target type, create a new `F` - * with the same target type, but with a source type of either `f`'s source - * type OR `g`'s source type. + * Given two `F`s (`f` and `g`) with a common target type, create a new `F` with the same target type, but with a + * source type of either `f`'s source type OR `g`'s source type. * * Example: * {{{ @@ -47,8 +46,7 @@ trait Choice[F[_, _]] extends Category[F] { def choice[A, B, C](f: F[A, C], g: F[B, C]): F[Either[A, B], C] /** - * An `F` that, given a source `A` on either the right or left side, will - * return that same `A` object. + * An `F` that, given a source `A` on either the right or left side, will return that same `A` object. * * Example: * {{{ diff --git a/core/src/main/scala/cats/arrow/CommutativeArrow.scala b/core/src/main/scala/cats/arrow/CommutativeArrow.scala index 0d72afa443..be89c5a3bb 100644 --- a/core/src/main/scala/cats/arrow/CommutativeArrow.scala +++ b/core/src/main/scala/cats/arrow/CommutativeArrow.scala @@ -23,8 +23,8 @@ package cats package arrow /** - * In a Commutative Arrow F[_, _], the split operation (or `***`) is commutative, - * which means that there is non-interference between the effect of the paired arrows. + * In a Commutative Arrow F[_, _], the split operation (or `***`) is commutative, which means that there is + * non-interference between the effect of the paired arrows. * * Must obey the laws in CommutativeArrowLaws */ diff --git a/core/src/main/scala/cats/arrow/Compose.scala b/core/src/main/scala/cats/arrow/Compose.scala index d39648161e..fdf9b09f50 100644 --- a/core/src/main/scala/cats/arrow/Compose.scala +++ b/core/src/main/scala/cats/arrow/Compose.scala @@ -26,6 +26,7 @@ package arrow * Must obey the laws defined in cats.laws.ComposeLaws. * * Here's how you can use `>>>` and `<<<` + * * Example: * {{{ * scala> import cats.syntax.all._ diff --git a/core/src/main/scala/cats/arrow/FunctionK.scala b/core/src/main/scala/cats/arrow/FunctionK.scala index a371919461..8038f6ba7d 100644 --- a/core/src/main/scala/cats/arrow/FunctionK.scala +++ b/core/src/main/scala/cats/arrow/FunctionK.scala @@ -25,11 +25,9 @@ package arrow import cats.data.{EitherK, Tuple2K} /** - * `FunctionK[F[_], G[_]]` is a functor transformation from `F` to `G` - * in the same manner that function `A => B` is a morphism from values - * of type `A` to `B`. - * An easy way to create a FunctionK instance is to use the Polymorphic - * lambdas provided by typelevel/kind-projector v0.9+. E.g. + * `FunctionK[F[_], G[_]]` is a functor transformation from `F` to `G` in the same manner that function `A => B` is a + * morphism from values of type `A` to `B`. An easy way to create a FunctionK instance is to use the Polymorphic lambdas + * provided by typelevel/kind-projector v0.9+. E.g. * {{{ * val listToOption = λ[FunctionK[List, Option]](_.headOption) * }}} @@ -42,32 +40,29 @@ trait FunctionK[F[_], G[_]] extends Serializable { self => def apply[A](fa: F[A]): G[A] /** - * Composes two instances of FunctionK into a new FunctionK with this - * transformation applied last. + * Composes two instances of FunctionK into a new FunctionK with this transformation applied last. */ def compose[E[_]](f: FunctionK[E, F]): FunctionK[E, G] = new FunctionK[E, G] { def apply[A](fa: E[A]): G[A] = self(f(fa)) } /** - * Composes two instances of FunctionK into a new FunctionK with this - * transformation applied first. + * Composes two instances of FunctionK into a new FunctionK with this transformation applied first. */ def andThen[H[_]](f: FunctionK[G, H]): FunctionK[F, H] = f.compose(self) /** - * Composes two instances of FunctionK into a new FunctionK that transforms - * a [[cats.data.EitherK]] to a single functor. + * Composes two instances of FunctionK into a new FunctionK that transforms a [[cats.data.EitherK]] to a single + * functor. * - * This transformation will be used to transform left `F` values while - * `h` will be used to transform right `H` values. + * This transformation will be used to transform left `F` values while `h` will be used to transform right `H` values. */ def or[H[_]](h: FunctionK[H, G]): FunctionK[EitherK[F, H, *], G] = new FunctionK[EitherK[F, H, *], G] { def apply[A](fa: EitherK[F, H, A]): G[A] = fa.fold(self, h) } /** - * Composes two instances of `FunctionK` into a new `FunctionK` that transforms - * one single functor to a [[cats.data.Tuple2K]] of two functors. + * Composes two instances of `FunctionK` into a new `FunctionK` that transforms one single functor to a + * [[cats.data.Tuple2K]] of two functors. * * {{{ * scala> import cats.arrow.FunctionK diff --git a/core/src/main/scala/cats/arrow/FunctionKLift.scala b/core/src/main/scala/cats/arrow/FunctionKLift.scala index 7f5dafb525..f9f7e70d63 100644 --- a/core/src/main/scala/cats/arrow/FunctionKLift.scala +++ b/core/src/main/scala/cats/arrow/FunctionKLift.scala @@ -33,9 +33,8 @@ private[arrow] trait FunctionKLift { * val lifted = FunctionK.liftFunction[List, Option](headOption) * }}} * - * Note: The weird `τ[F, G]` parameter is there to compensate for - * the lack of polymorphic function types in Scala 2. - * + * Note: The weird `τ[F, G]` parameter is there to compensate for the lack of polymorphic function types in Scala 2. + * * It is present in the Scala 3 API to simplify cross-compilation. */ def liftFunction[F[_], G[_]](f: F[τ[F, G]] => G[τ[F, G]]): FunctionK[F, G] = diff --git a/core/src/main/scala/cats/arrow/Profunctor.scala b/core/src/main/scala/cats/arrow/Profunctor.scala index 8a699aed30..69a31c3341 100644 --- a/core/src/main/scala/cats/arrow/Profunctor.scala +++ b/core/src/main/scala/cats/arrow/Profunctor.scala @@ -23,8 +23,8 @@ package cats package arrow /** - * A [[Profunctor]] is a [[Contravariant]] functor on its first type parameter - * and a [[Functor]] on its second type parameter. + * A [[Profunctor]] is a [[Contravariant]] functor on its first type parameter and a [[Functor]] on its second type + * parameter. * * Must obey the laws defined in cats.laws.ProfunctorLaws. */ @@ -61,6 +61,7 @@ trait Profunctor[F[_, _]] extends Serializable { self => /** * Narrows A into a subtype AA. + * * Example: * {{{ * scala> import cats.syntax.profunctor._ @@ -76,6 +77,7 @@ trait Profunctor[F[_, _]] extends Serializable { self => /** * Widens B into a supertype BB. + * * Example: * {{{ * scala> import cats.syntax.profunctor._ diff --git a/core/src/main/scala/cats/data/AndThen.scala b/core/src/main/scala/cats/data/AndThen.scala index 05639733cd..0f760f704d 100644 --- a/core/src/main/scala/cats/data/AndThen.scala +++ b/core/src/main/scala/cats/data/AndThen.scala @@ -27,9 +27,8 @@ import cats.arrow.{ArrowChoice, CommutativeArrow} import scala.annotation.tailrec /** - * A function type of a single input that can do function composition - * (via `andThen` and `compose`) in constant stack space with amortized - * linear time application (in the number of constituent functions). + * A function type of a single input that can do function composition (via `andThen` and `compose`) in constant stack + * space with amortized linear time application (in the number of constituent functions). * * Example: * @@ -41,17 +40,14 @@ import scala.annotation.tailrec * f(0) * }}} * - * This can be used to build stack safe data structures that make - * use of lambdas. The perfect candidates for usage with `AndThen` - * are the data structures using a signature like this (where - * `F[_]` is a monadic type): + * This can be used to build stack safe data structures that make use of lambdas. The perfect candidates for usage with + * `AndThen` are the data structures using a signature like this (where `F[_]` is a monadic type): * * {{{ * A => F[B] * }}} * - * As an example, if we described this data structure, the naive - * solution for that `map` is stack unsafe: + * As an example, if we described this data structure, the naive solution for that `map` is stack unsafe: * * {{{ * case class Resource[F[_], A, B]( @@ -69,8 +65,7 @@ import scala.annotation.tailrec * } * }}} * - * To describe a `flatMap` operation for this data type, `AndThen` - * can save the day: + * To describe a `flatMap` operation for this data type, `AndThen` can save the day: * * {{{ * def flatMap[C](f: B => C)(implicit F: Functor[F]): Resource[F, A, C] = { @@ -169,21 +164,19 @@ object AndThen extends AndThenInstances0 { final private case class Concat[-A, E, +B](left: AndThen[A, E], right: AndThen[E, B]) extends AndThen[A, B] /** - * Establishes the maximum stack depth when fusing `andThen` or - * `compose` calls. + * Establishes the maximum stack depth when fusing `andThen` or `compose` calls. * * The default is `128`. * - * This value was reached by taking into account the default stack - * size as set on 32 bits or 64 bits, Linux or Windows systems, - * being enough to notice performance gains, but not big enough - * to be in danger of triggering a stack-overflow error. + * This value was reached by taking into account the default stack size as set on 32 bits or 64 bits, Linux or Windows + * systems, being enough to notice performance gains, but not big enough to be in danger of triggering a + * stack-overflow error. */ final private val fusionMaxStackDepth = 128 /** - * If you are going to call this function many times, right associating it - * once can be a significant performance improvement for VERY long chains. + * If you are going to call this function many times, right associating it once can be a significant performance + * improvement for VERY long chains. */ def toRightAssociated[A, B](fn: AndThen[A, B]): AndThen[A, B] = { @tailrec @@ -224,8 +217,7 @@ object AndThen extends AndThenInstances0 { } /** - * true if this fn is already right associated, which is the faster - * for calling + * true if this fn is already right associated, which is the faster for calling */ @tailrec final def isRightAssociated[A, B](fn: AndThen[A, B]): Boolean = @@ -306,9 +298,8 @@ abstract private[data] class AndThenInstances0 extends AndThenInstances1 { } /** - * [[cats.arrow.ArrowChoice ArrowChoice]] and - * [[cats.arrow.CommutativeArrow CommutativeArrow]] instances - * for [[AndThen]]. + * [[cats.arrow.ArrowChoice ArrowChoice]] and [[cats.arrow.CommutativeArrow CommutativeArrow]] instances for + * [[AndThen]]. */ implicit val catsDataArrowForAndThen: ArrowChoice[AndThen] & CommutativeArrow[AndThen] = new ArrowChoice[AndThen] with CommutativeArrow[AndThen] { diff --git a/core/src/main/scala/cats/data/Binested.scala b/core/src/main/scala/cats/data/Binested.scala index b86c8dc503..e626dfa07e 100644 --- a/core/src/main/scala/cats/data/Binested.scala +++ b/core/src/main/scala/cats/data/Binested.scala @@ -25,11 +25,10 @@ package data import cats.arrow.* /** - * Compose a two-slot type constructor `F[_, _]` with two single-slot type constructors - * `G[_]` and `H[_]`, resulting in a two-slot type constructor with respect to the inner types. - * For example, `List` and `Option` both have `Functor` instances, and `Either` has a - * `Bifunctor` instance. Therefore, `Binested[Either, List, Option, *, *]` has a `Bifunctor` - * instance as well: + * Compose a two-slot type constructor `F[_, _]` with two single-slot type constructors `G[_]` and `H[_]`, resulting in + * a two-slot type constructor with respect to the inner types. For example, `List` and `Option` both have `Functor` + * instances, and `Either` has a `Bifunctor` instance. Therefore, `Binested[Either, List, Option, *, *]` has a + * `Bifunctor` instance as well: * * {{{ * scala> import cats.Bifunctor diff --git a/core/src/main/scala/cats/data/Chain.scala b/core/src/main/scala/cats/data/Chain.scala index b54f124700..b0d4c27442 100644 --- a/core/src/main/scala/cats/data/Chain.scala +++ b/core/src/main/scala/cats/data/Chain.scala @@ -70,9 +70,8 @@ import Chain.{ } /** - * Trivial catenable sequence. Supports O(1) append, and (amortized) - * O(1) `uncons`, such that walking the sequence via N successive `uncons` - * steps takes O(N). + * Trivial catenable sequence. Supports O(1) append, and (amortized) O(1) `uncons`, such that walking the sequence via N + * successive `uncons` steps takes O(N). */ sealed abstract class Chain[+A] extends ChainCompat[A] { @@ -243,8 +242,10 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { /** * Takes longest prefix of elements that satisfy a predicate. - * @param p The predicate used to test elements. - * @return the longest prefix of this chain whose elements all satisfy the predicate p. + * @param p + * The predicate used to test elements. + * @return + * the longest prefix of this chain whose elements all satisfy the predicate p. */ final def takeWhile(p: A => Boolean): Chain[A] = { var result = Chain.empty[A] @@ -352,8 +353,10 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { /** * Drops longest prefix of elements that satisfy a predicate. * - * @param p The predicate used to test elements. - * @return the longest suffix of this sequence whose first element does not satisfy the predicate p. + * @param p + * The predicate used to test elements. + * @return + * the longest suffix of this sequence whose first element does not satisfy the predicate p. */ final def dropWhile(p: A => Boolean): Chain[A] = { @tailrec @@ -489,8 +492,8 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { } /** - * Finds the first element of this `Chain` for which the given partial - * function is defined, and applies the partial function to it. + * Finds the first element of this `Chain` for which the given partial function is defined, and applies the partial + * function to it. */ final def collectFirst[B](pf: PartialFunction[A, B]): Option[B] = { var result: Option[B] = None @@ -506,8 +509,7 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { } /** - * Like `collectFirst` from `scala.collection.Traversable` but takes `A => Option[B]` - * instead of `PartialFunction`s. + * Like `collectFirst` from `scala.collection.Traversable` but takes `A => Option[B]` instead of `PartialFunction`s. */ final def collectFirstSome[B](f: A => Option[B]): Option[B] = { var result: Option[B] = None @@ -608,8 +610,7 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { } /** - * Groups elements inside this `Chain` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `Chain` according to the `Order` of the keys produced by the given mapping function. * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -626,10 +627,8 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { groupMap(key = f)(identity) /** - * Groups elements inside this `Chain` according to the `Order` - * of the keys produced by the given key function. - * And each element in a group is transformed into a value of type B - * using the mapping function. + * Groups elements inside this `Chain` according to the `Order` of the keys produced by the given key function. And + * each element in a group is transformed into a value of type B using the mapping function. * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -659,12 +658,9 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { } /** - * Groups elements inside this `Chain` according to the `Order` - * of the keys produced by the given key function. - * Then each element in a group is transformed into a value of type B - * using the mapping function. - * And finally they are all reduced into a single value - * using their `Semigroup` + * Groups elements inside this `Chain` according to the `Order` of the keys produced by the given key function. Then + * each element in a group is transformed into a value of type B using the mapping function. And finally they are all + * reduced into a single value using their `Semigroup` * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -681,12 +677,9 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { groupMapReduceWith(key)(f)(S.combine) /** - * Groups elements inside this `Chain` according to the `Order` - * of the keys produced by the given key function. - * Then each element in a group is transformed into a value of type B - * using the mapping function. - * And finally they are all reduced into a single value - * using the provided combine function. + * Groups elements inside this `Chain` according to the `Order` of the keys produced by the given key function. Then + * each element in a group is transformed into a value of type B using the mapping function. And finally they are all + * reduced into a single value using the provided combine function. * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -754,9 +747,8 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { } /** - * Yields to Some(a, Chain[A]) with `a` removed where `f` holds for the first time, - * otherwise yields None, if `a` was not found - * Traverses only until `a` is found. + * Yields to Some(a, Chain[A]) with `a` removed where `f` holds for the first time, otherwise yields None, if `a` was + * not found Traverses only until `a` is found. */ final def deleteFirst(f: A => Boolean): Option[(A, Chain[A])] = { @tailrec @@ -873,16 +865,16 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { /** * Compares the length of this chain to a test value. * - * The method does not call `length` directly; its running time - * is `O(length min len)` instead of `O(length)`. + * The method does not call `length` directly; its running time is `O(length min len)` instead of `O(length)`. * - * @param len the test value that gets compared with the length. - * @return a negative value if `this.length < len`, - * zero if `this.length == len` or - * a positive value if `this.length > len`. - * @note an adapted version of - [[https://github.com/scala/scala/blob/v2.13.8/src/library/scala/collection/Iterable.scala#L272-L288 Iterable#sizeCompare]] - from Scala Library v2.13.10 is used in a part of the implementation. + * @param len + * the test value that gets compared with the length. + * @return + * a negative value if `this.length < len`, zero if `this.length == len` or a positive value if `this.length > len`. + * @note + * an adapted version of + * [[https://github.com/scala/scala/blob/v2.13.8/src/library/scala/collection/Iterable.scala#L272-L288 Iterable#sizeCompare]] + * from Scala Library v2.13.10 is used in a part of the implementation. * * {{{ * scala> import cats.data.Chain @@ -959,10 +951,8 @@ sealed abstract class Chain[+A] extends ChainCompat[A] { /** * Typesafe equality operator. * - * This method is similar to == except that it only allows two - * Chain[A] values to be compared to each other, and uses - * equality provided by Eq[_] instances, rather than using the - * universal equality provided by .equals. + * This method is similar to == except that it only allows two Chain[A] values to be compared to each other, and uses + * equality provided by Eq[_] instances, rather than using the universal equality provided by .equals. */ def ===[AA >: A](that: Chain[AA])(implicit A: Eq[AA]): Boolean = (this eq that) || { diff --git a/core/src/main/scala/cats/data/Const.scala b/core/src/main/scala/cats/data/Const.scala index 4d620a78b0..f179cfccba 100644 --- a/core/src/main/scala/cats/data/Const.scala +++ b/core/src/main/scala/cats/data/Const.scala @@ -27,8 +27,8 @@ import cats.kernel.{CommutativeMonoid, CommutativeSemigroup, LowerBounded, Upper import scala.annotation.nowarn /** - * [[Const]] is a phantom type, it does not contain a value of its second type parameter `B` - * [[Const]] can be seen as a type level version of `Function.const[A, B]: A => B => A` + * [[Const]] is a phantom type, it does not contain a value of its second type parameter `B` [[Const]] can be seen as a + * type level version of `Function.const[A, B]: A => B => A` */ final case class Const[A, B](getConst: A) { @@ -66,7 +66,9 @@ object Const extends ConstInstances { Const(A.empty) /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class OfPartiallyApplied[B](private val dummy: Boolean = true) extends AnyVal { def apply[A](a: A): Const[A, B] = Const(a) diff --git a/core/src/main/scala/cats/data/ContT.scala b/core/src/main/scala/cats/data/ContT.scala index 6d260f5d9c..ef63db25f0 100644 --- a/core/src/main/scala/cats/data/ContT.scala +++ b/core/src/main/scala/cats/data/ContT.scala @@ -23,11 +23,9 @@ package cats package data /** - * This is a continuation transformer based on the ContT in - * the Haskell package Control.Monad.Cont + * This is a continuation transformer based on the ContT in the Haskell package Control.Monad.Cont * - * This is reasonably straight-forward except that to make - * a tailRecM implementation we leverage the Defer type class to + * This is reasonably straight-forward except that to make a tailRecM implementation we leverage the Defer type class to * obtain stack-safety. */ sealed abstract class ContT[M[_], A, +B] extends Serializable { @@ -159,8 +157,7 @@ object ContT { /** * Similar to [[pure]] but evaluation of the argument is deferred. * - * This is useful for building a computation which calls its continuation as the final step. - * Instead of writing: + * This is useful for building a computation which calls its continuation as the final step. Instead of writing: * * {{{ * ContT.apply { cb => diff --git a/core/src/main/scala/cats/data/EitherK.scala b/core/src/main/scala/cats/data/EitherK.scala index f462a8c8a1..41fc623187 100644 --- a/core/src/main/scala/cats/data/EitherK.scala +++ b/core/src/main/scala/cats/data/EitherK.scala @@ -28,7 +28,8 @@ import cats.arrow.FunctionK /** * `F` on the left and `G` on the right of `scala.util.Either`. * - * @param run The underlying `scala.util.Either`. + * @param run + * The underlying `scala.util.Either`. */ final case class EitherK[F[_], G[_], A](run: Either[F[A], G[A]]) { diff --git a/core/src/main/scala/cats/data/EitherT.scala b/core/src/main/scala/cats/data/EitherT.scala index 9339255a75..3c0056237b 100644 --- a/core/src/main/scala/cats/data/EitherT.scala +++ b/core/src/main/scala/cats/data/EitherT.scala @@ -26,11 +26,11 @@ import cats.Bifunctor import cats.syntax.EitherUtil /** - * Transformer for `Either`, allowing the effect of an arbitrary type constructor `F` to be combined with the - * fail-fast effect of `Either`. + * Transformer for `Either`, allowing the effect of an arbitrary type constructor `F` to be combined with the fail-fast + * effect of `Either`. * - * `EitherT[F, A, B]` wraps a value of type `F[Either[A, B]]`. An `F[C]` can be lifted in to `EitherT[F, A, C]` via `EitherT.right`, - * and lifted in to a `EitherT[F, C, B]` via `EitherT.left`. + * `EitherT[F, A, B]` wraps a value of type `F[Either[A, B]]`. An `F[C]` can be lifted in to `EitherT[F, A, C]` via + * `EitherT.right`, and lifted in to a `EitherT[F, C, B]` via `EitherT.left`. */ final case class EitherT[F[_], A, B](value: F[Either[A, B]]) { @@ -133,18 +133,17 @@ final case class EitherT[F[_], A, B](value: F[Either[A, B]]) { case Right(b) => F.pure(b) } - /*** - * + /** * Like [[getOrElseF]] but accept an error `E` and raise it when the inner `Either` is `Left` - * + * * Equivalent to `getOrElseF(F.raiseError(e)))` - * + * * Example: * {{{ * scala> import cats.data.EitherT * scala> import cats.syntax.all._ * scala> import scala.util.{Success, Failure, Try} - + * * scala> val eitherT: EitherT[Try,String,Int] = EitherT[Try,String,Int](Success(Left("abc"))) * scala> eitherT.getOrRaise(new RuntimeException("ERROR!")) * res0: Try[Int] = Failure(java.lang.RuntimeException: ERROR!) @@ -218,10 +217,8 @@ final case class EitherT[F[_], A, B](value: F[Either[A, B]]) { }) /** - * Inverse of `MonadError#attemptT` - * Given MonadError[F, E :> A] transforms Either[F, A, B] to F[B] - * If the value was B, F[B] is successful - * If the value was A, F[B] is failed with E + * Inverse of `MonadError#attemptT` Given MonadError[F, E :> A] transforms Either[F, A, B] to F[B] If the value was B, + * F[B] is successful If the value was A, F[B] is failed with E * * Example: * {{{ @@ -619,8 +616,8 @@ final case class EitherT[F[_], A, B](value: F[Either[A, B]]) { /** * Run this value as a `[[Validated]]` against the function and convert it back to an `[[EitherT]]`. * - * The [[Applicative]] instance for `EitherT` "fails fast" - it is often useful to "momentarily" have - * it accumulate errors instead, which is what the `[[Validated]]` data type gives us. + * The [[Applicative]] instance for `EitherT` "fails fast" - it is often useful to "momentarily" have it accumulate + * errors instead, which is what the `[[Validated]]` data type gives us. * * Example: * {{{ @@ -641,9 +638,9 @@ final case class EitherT[F[_], A, B](value: F[Either[A, B]]) { /** * Transform this `EitherT[F, A, B]` into a `[[Nested]][F, Either[A, *], B]`. * - * An example where `toNested` can be used, is to get the `Apply.ap` function with the - * behavior from the composed `Apply` instances from `F` and `Either[A, *]`, which is - * inconsistent with the behavior of the `ap` from `Monad` of `EitherT`. + * An example where `toNested` can be used, is to get the `Apply.ap` function with the behavior from the composed + * `Apply` instances from `F` and `Either[A, *]`, which is inconsistent with the behavior of the `ap` from `Monad` of + * `EitherT`. * * {{{ * scala> import cats.data.EitherT @@ -702,7 +699,8 @@ final case class EitherT[F[_], A, B](value: F[Either[A, B]]) { } ) - /** Convert this `EitherT[F, A, B]` into an `IorT[F, A, B]`. + /** + * Convert this `EitherT[F, A, B]` into an `IorT[F, A, B]`. */ def toIor(implicit F: Functor[F]): IorT[F, A, B] = IorT.fromEitherF(value) @@ -711,7 +709,9 @@ final case class EitherT[F[_], A, B](value: F[Either[A, B]]) { object EitherT extends EitherTInstances { /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class LeftPartiallyApplied[B](private val dummy: Boolean = true) extends AnyVal { def apply[F[_], A](fa: F[A])(implicit F: Functor[F]): EitherT[F, A, B] = EitherT(F.map(fa)(Left(_))) @@ -729,7 +729,9 @@ object EitherT extends EitherTInstances { final def left[B]: LeftPartiallyApplied[B] = new LeftPartiallyApplied[B] /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class LeftTPartiallyApplied[F[_], B](private val dummy: Boolean = true) extends AnyVal { def apply[A](a: A)(implicit F: Applicative[F]): EitherT[F, A, B] = EitherT(F.pure(Left(a))) @@ -747,7 +749,9 @@ object EitherT extends EitherTInstances { final def leftT[F[_], B]: LeftTPartiallyApplied[F, B] = new LeftTPartiallyApplied[F, B] /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class RightPartiallyApplied[A](private val dummy: Boolean = true) extends AnyVal { def apply[F[_], B](fb: F[B])(implicit F: Functor[F]): EitherT[F, A, B] = EitherT(F.map(fb)(Right(_))) @@ -765,7 +769,9 @@ object EitherT extends EitherTInstances { final def right[A]: RightPartiallyApplied[A] = new RightPartiallyApplied[A] /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class PurePartiallyApplied[F[_], A](private val dummy: Boolean = true) extends AnyVal { def apply[B](b: B)(implicit F: Applicative[F]): EitherT[F, A, B] = EitherT(F.pure(Right(b))) @@ -848,8 +854,8 @@ object EitherT extends EitherTInstances { /** * Transforms an `Either` into an `EitherT`, lifted into the specified `Applicative`. * - * Note: The return type is a FromEitherPartiallyApplied[F], which has an apply method - * on it, allowing you to call fromEither like this: + * Note: The return type is a FromEitherPartiallyApplied[F], which has an apply method on it, allowing you to call + * fromEither like this: * {{{ * scala> import cats.syntax.all._ * scala> val t: Either[String, Int] = Either.right(3) @@ -862,7 +868,9 @@ object EitherT extends EitherTInstances { final def fromEither[F[_]]: FromEitherPartiallyApplied[F] = new FromEitherPartiallyApplied /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class FromEitherPartiallyApplied[F[_]](private val dummy: Boolean = true) extends AnyVal { def apply[E, A](either: Either[E, A])(implicit F: Applicative[F]): EitherT[F, E, A] = @@ -870,8 +878,8 @@ object EitherT extends EitherTInstances { } /** - * Transforms an `Option` into an `EitherT`, lifted into the specified `Applicative` and using - * the second argument if the `Option` is a `None`. + * Transforms an `Option` into an `EitherT`, lifted into the specified `Applicative` and using the second argument if + * the `Option` is a `None`. * {{{ * scala> import cats.syntax.all._ * scala> val o: Option[Int] = None @@ -884,7 +892,9 @@ object EitherT extends EitherTInstances { final def fromOption[F[_]]: FromOptionPartiallyApplied[F] = new FromOptionPartiallyApplied /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class FromOptionPartiallyApplied[F[_]](private val dummy: Boolean = true) extends AnyVal { def apply[E, A](opt: Option[A], ifNone: => E)(implicit F: Applicative[F]): EitherT[F, E, A] = @@ -929,9 +939,8 @@ object EitherT extends EitherTInstances { ) /** - * If the condition is satisfied, return the given `A` in `Right` - * lifted into the specified `Applicative`, otherwise, return the - * given `E` in `Left` lifted into the specified `Applicative`. + * If the condition is satisfied, return the given `A` in `Right` lifted into the specified `Applicative`, otherwise, + * return the given `E` in `Left` lifted into the specified `Applicative`. * * {{{ * scala> import cats.Id @@ -947,7 +956,9 @@ object EitherT extends EitherTInstances { final def cond[F[_]]: CondPartiallyApplied[F] = new CondPartiallyApplied /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class CondPartiallyApplied[F[_]](private val dummy: Boolean = true) extends AnyVal { def apply[E, A](test: Boolean, right: => A, left: => E)(implicit F: Applicative[F]): EitherT[F, E, A] = @@ -990,15 +1001,12 @@ abstract private[data] class EitherTInstances extends EitherTInstances1 { accumulatingParallel[M, E] /** - * An alternative [[Parallel]] implementation which merges the semantics of - * the outer Parallel (the F[_] effect) with the effects of the inner - * one (the Either). The inner Parallel has the semantics of [[Validated]], - * while the outer has the semantics of parallel ''evaluation'' (in most cases). - * The default Parallel for [[EitherT]], when the nested F also has a Parallel, - * is to strictly take the semantics of the nested F and to short-circuit any - * lefts (often, errors) in a left-to-right fashion, mirroring the semantics of - * [[Applicative]] on EitherT. This instance is different in that it will not - * ''short-circuit'' but instead accumulate all lefts according to the supplied + * An alternative [[Parallel]] implementation which merges the semantics of the outer Parallel (the F[_] effect) with + * the effects of the inner one (the Either). The inner Parallel has the semantics of [[Validated]], while the outer + * has the semantics of parallel ''evaluation'' (in most cases). The default Parallel for [[EitherT]], when the nested + * F also has a Parallel, is to strictly take the semantics of the nested F and to short-circuit any lefts (often, + * errors) in a left-to-right fashion, mirroring the semantics of [[Applicative]] on EitherT. This instance is + * different in that it will not ''short-circuit'' but instead accumulate all lefts according to the supplied * [[Semigroup]], similar to Validated. * * {{{ @@ -1137,8 +1145,7 @@ abstract private[data] class EitherTInstances1 extends EitherTInstances2 { abstract private[data] class EitherTInstances2 extends EitherTInstances3 { /** - * Monad error instance for recovering errors in F instead of - * the underlying Either. + * Monad error instance for recovering errors in F instead of the underlying Either. * * {{{ * scala> import cats.data.EitherT diff --git a/core/src/main/scala/cats/data/IndexedReaderWriterStateT.scala b/core/src/main/scala/cats/data/IndexedReaderWriterStateT.scala index ca6bc53df0..0bba128fe1 100644 --- a/core/src/main/scala/cats/data/IndexedReaderWriterStateT.scala +++ b/core/src/main/scala/cats/data/IndexedReaderWriterStateT.scala @@ -25,11 +25,11 @@ package data import cats.arrow.{Profunctor, Strong} /** - * Represents a stateful computation in a context `F[_]`, from state `SA` to state `SB`, - * with an initial environment `E`, an accumulated log `L` and a result `A`. + * Represents a stateful computation in a context `F[_]`, from state `SA` to state `SB`, with an initial environment + * `E`, an accumulated log `L` and a result `A`. * - * In other words, it is a pre-baked stack of `[[ReaderT]][F, E, A]`, `[[WriterT]][F, L, A]` - * and `[[IndexedStateT]][F, SA, SB, A]`. + * In other words, it is a pre-baked stack of `[[ReaderT]][F, E, A]`, `[[WriterT]][F, L, A]` and + * `[[IndexedStateT]][F, SA, SB, A]`. */ final class IndexedReaderWriterStateT[F[_], E, L, SA, SB, A](val runF: F[(E, SA) => F[(L, SB, A)]]) extends Serializable { @@ -118,8 +118,8 @@ final class IndexedReaderWriterStateT[F[_], E, L, SA, SB, A](val runF: F[(E, SA) } /** - * Modify the result of the computation by feeding it into `f`, threading the state - * through the resulting computation and combining the log values. + * Modify the result of the computation by feeding it into `f`, threading the state through the resulting computation + * and combining the log values. */ def flatMap[SC, B]( f: A => IndexedReaderWriterStateT[F, E, L, SB, SC, B] @@ -489,11 +489,11 @@ object IndexedReaderWriterStateT extends IRWSTInstances with CommonIRWSTConstruc /** * Internal API — shifts the execution of `run` in the `F` context. * - * Used to build IndexedReaderWriterStateT values for `F[_]` data types that implement `Monad`, - * in which case it is safer to trigger the `F[_]` context earlier. + * Used to build IndexedReaderWriterStateT values for `F[_]` data types that implement `Monad`, in which case it is + * safer to trigger the `F[_]` context earlier. * - * This is needed for [[IndexedReaderWriterStateT.flatMap]] to be stack-safe when the underlying F[_] is, - * for further explanation see [[Kleisli.shift]]. + * This is needed for [[IndexedReaderWriterStateT.flatMap]] to be stack-safe when the underlying F[_] is, for further + * explanation see [[Kleisli.shift]]. */ private[data] def shift[F[_], E, L, SA, SB, A]( runF: F[(E, SA) => F[(L, SB, A)]] diff --git a/core/src/main/scala/cats/data/IndexedStateT.scala b/core/src/main/scala/cats/data/IndexedStateT.scala index ead627a2c7..9cfc987225 100644 --- a/core/src/main/scala/cats/data/IndexedStateT.scala +++ b/core/src/main/scala/cats/data/IndexedStateT.scala @@ -25,14 +25,12 @@ package data import cats.arrow.{Profunctor, Strong} /** - * `IndexedStateT[F, SA, SB, A]` is a stateful computation in a context `F` yielding - * a value of type `A`. The state transitions from a value of type `SA` to a value - * of type `SB`. + * `IndexedStateT[F, SA, SB, A]` is a stateful computation in a context `F` yielding a value of type `A`. The state + * transitions from a value of type `SA` to a value of type `SB`. * - * Note that for the `SA != SB` case, this is an indexed monad. Indexed monads - * are monadic type constructors annotated by an additional type for effect - * tracking purposes. In this case, the annotation tracks the initial state and - * the resulting state. + * Note that for the `SA != SB` case, this is an indexed monad. Indexed monads are monadic type constructors annotated + * by an additional type for effect tracking purposes. In this case, the annotation tracks the initial state and the + * resulting state. * * Given `IndexedStateT[F, S, S, A]`, this yields the `StateT[F, S, A]` monad. */ @@ -85,14 +83,12 @@ final class IndexedStateT[F[_], SA, SB, A](val runF: F[SA => F[(SB, A)]]) extend F.flatMap(runF)(f => f(initial)) /** - * Run with the provided initial state value and return the final state - * (discarding the final value). + * Run with the provided initial state value and return the final state (discarding the final value). */ def runS(s: SA)(implicit F: FlatMap[F]): F[SB] = F.map(run(s))(_._1) /** - * Run with the provided initial state value and return the final value - * (discarding the final state). + * Run with the provided initial state value and return the final value (discarding the final state). */ def runA(s: SA)(implicit F: FlatMap[F]): F[A] = F.map(run(s))(_._2) @@ -102,14 +98,12 @@ final class IndexedStateT[F[_], SA, SB, A](val runF: F[SA => F[(SB, A)]]) extend def runEmpty(implicit S: Monoid[SA], F: FlatMap[F]): F[(SB, A)] = run(S.empty) /** - * Run with `S`'s empty monoid value as the initial state and return the final - * state (discarding the final value). + * Run with `S`'s empty monoid value as the initial state and return the final state (discarding the final value). */ def runEmptyS(implicit S: Monoid[SA], F: FlatMap[F]): F[SB] = runS(S.empty) /** - * Run with `S`'s empty monoid value as the initial state and return the final - * value (discarding the final state). + * Run with `S`'s empty monoid value as the initial state and return the final value (discarding the final state). */ def runEmptyA(implicit S: Monoid[SA], F: FlatMap[F]): F[A] = runA(S.empty) @@ -146,8 +140,8 @@ final class IndexedStateT[F[_], SA, SB, A](val runF: F[SA => F[(SB, A)]]) extend /** * Transform the state used. * - * This is useful when you are working with many focused `StateT`s and want to pass in a - * global state containing the various states needed for each individual `StateT`. + * This is useful when you are working with many focused `StateT`s and want to pass in a global state containing the + * various states needed for each individual `StateT`. * * {{{ * scala> import cats.syntax.all._ // needed for StateT.apply diff --git a/core/src/main/scala/cats/data/Ior.scala b/core/src/main/scala/cats/data/Ior.scala index 5227b5cab1..757cd2b284 100644 --- a/core/src/main/scala/cats/data/Ior.scala +++ b/core/src/main/scala/cats/data/Ior.scala @@ -31,18 +31,18 @@ import scala.annotation.tailrec * Represents a right-biased disjunction that is either an `A`, or a `B`, or both an `A` and a `B`. * * An instance of `A [[Ior]] B` is one of: - * - `[[Ior.Left Left]][A]` - * - `[[Ior.Right Right]][B]` - * - `[[Ior.Both Both]][A, B]` + * - `[[Ior.Left Left]][A]` + * - `[[Ior.Right Right]][B]` + * - `[[Ior.Both Both]][A, B]` * - * `A [[Ior]] B` is similar to `scala.util.Either[A, B]`, except that it can represent the simultaneous presence of - * an `A` and a `B`. It is right-biased so methods such as `map` and `flatMap` operate on the - * `B` value. Some methods, like `flatMap`, handle the presence of two [[Ior.Both Both]] values using a - * `[[Semigroup]][A]`, while other methods, like [[toEither]], ignore the `A` value in a [[Ior.Both Both]]. + * `A [[Ior]] B` is similar to `scala.util.Either[A, B]`, except that it can represent the simultaneous presence of an + * `A` and a `B`. It is right-biased so methods such as `map` and `flatMap` operate on the `B` value. Some methods, like + * `flatMap`, handle the presence of two [[Ior.Both Both]] values using a `[[Semigroup]][A]`, while other methods, like + * [[toEither]], ignore the `A` value in a [[Ior.Both Both]]. * - * `A [[Ior]] B` is isomorphic to `Either[Either[A, B], (A, B)]`, but provides methods biased toward `B` - * values, regardless of whether the `B` values appear in a [[Ior.Right Right]] or a [[Ior.Both Both]]. - * The isomorphic `scala.util.Either` form can be accessed via the [[unwrap]] method. + * `A [[Ior]] B` is isomorphic to `Either[Either[A, B], (A, B)]`, but provides methods biased toward `B` values, + * regardless of whether the `B` values appear in a [[Ior.Right Right]] or a [[Ior.Both Both]]. The isomorphic + * `scala.util.Either` form can be accessed via the [[unwrap]] method. */ sealed abstract class Ior[+A, +B] extends Product with Serializable { @@ -1049,12 +1049,14 @@ sealed private[data] trait IorFunctions { /** * Create an `Ior` from two Options if at least one of them is defined. * - * @param oa an element (optional) for the left side of the `Ior` - * @param ob an element (optional) for the right side of the `Ior` + * @param oa + * an element (optional) for the left side of the `Ior` + * @param ob + * an element (optional) for the right side of the `Ior` * - * @return `None` if both `oa` and `ob` are `None`. Otherwise `Some` wrapping - * an [[Ior.Left]], [[Ior.Right]], or [[Ior.Both]] if `oa`, `ob`, or both are - * defined (respectively). + * @return + * `None` if both `oa` and `ob` are `None`. Otherwise `Some` wrapping an [[Ior.Left]], [[Ior.Right]], or + * [[Ior.Both]] if `oa`, `ob`, or both are defined (respectively). * * Example: * {{{ @@ -1084,10 +1086,11 @@ sealed private[data] trait IorFunctions { /** * Create an `Ior` from an `Either`. - * @param eab an `Either` from which the `Ior` should be created + * @param eab + * an `Either` from which the `Ior` should be created * - * @return [[Ior.Left]] if the `Either` was a `Left`, - * or [[Ior.Right]] if the `Either` was a `Right` + * @return + * [[Ior.Left]] if the `Either` was a `Left`, or [[Ior.Right]] if the `Either` was a `Right` * * Example: * {{{ diff --git a/core/src/main/scala/cats/data/IorT.scala b/core/src/main/scala/cats/data/IorT.scala index aa04b9f9dc..a2a472bf3e 100644 --- a/core/src/main/scala/cats/data/IorT.scala +++ b/core/src/main/scala/cats/data/IorT.scala @@ -61,8 +61,7 @@ final case class IorT[F[_], A, B](value: F[Ior[A, B]]) { case Ior.Both(_, b) => F.pure(b) } - /*** - * + /** * Like [[getOrElseF]] but accept an error `E` and raise it when the inner `Ior` is `Left` * * Equivalent to `getOrElseF(F.raiseError(e)))` @@ -72,7 +71,7 @@ final case class IorT[F[_], A, B](value: F[Ior[A, B]]) { * scala> import cats.data.IorT * scala> import cats.syntax.all._ * scala> import scala.util.{Success, Failure, Try} - + * * scala> val iorT: IorT[Try,String,Int] = IorT.leftT("abc") * scala> iorT.getOrRaise(new RuntimeException("ERROR!")) * res0: Try[Int] = Failure(java.lang.RuntimeException: ERROR!) @@ -185,7 +184,9 @@ final case class IorT[F[_], A, B](value: F[Ior[A, B]]) { object IorT extends IorTInstances { /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class LeftPartiallyApplied[B](private val dummy: Boolean = true) extends AnyVal { def apply[F[_], A](fa: F[A])(implicit F: Functor[F]): IorT[F, A, B] = IorT(F.map(fa)(Ior.left)) @@ -203,7 +204,9 @@ object IorT extends IorTInstances { final def left[B]: LeftPartiallyApplied[B] = new LeftPartiallyApplied[B] /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class LeftTPartiallyApplied[F[_], B](private val dummy: Boolean = true) extends AnyVal { def apply[A](a: A)(implicit F: Applicative[F]): IorT[F, A, B] = IorT(F.pure(Ior.left(a))) @@ -222,7 +225,9 @@ object IorT extends IorTInstances { final def leftT[F[_], B]: LeftTPartiallyApplied[F, B] = new LeftTPartiallyApplied[F, B] /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class RightPartiallyApplied[A](private val dummy: Boolean = true) extends AnyVal { def apply[F[_], B](fb: F[B])(implicit F: Functor[F]): IorT[F, A, B] = IorT(F.map(fb)(Ior.right)) @@ -263,7 +268,9 @@ object IorT extends IorTInstances { IorT(F.map2(fa, fb)((a, b) => Ior.Both(a, b))) /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class BothTPartiallyApplied[F[_]](private val dummy: Boolean = true) extends AnyVal { def apply[A, B](a: A, b: B)(implicit F: Applicative[F]): IorT[F, A, B] = IorT(F.pure(Ior.Both(a, b))) @@ -281,7 +288,9 @@ object IorT extends IorTInstances { final def bothT[F[_]]: BothTPartiallyApplied[F] = new BothTPartiallyApplied[F] /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class PurePartiallyApplied[F[_], A](private val dummy: Boolean = true) extends AnyVal { def apply[B](b: B)(implicit F: Applicative[F]): IorT[F, A, B] = IorT(F.pure(Ior.right(b))) @@ -329,7 +338,9 @@ object IorT extends IorTInstances { } /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class FromIorPartiallyApplied[F[_]](private val dummy: Boolean = true) extends AnyVal { def apply[A, B](ior: Ior[A, B])(implicit F: Applicative[F]): IorT[F, A, B] = IorT(F.pure(ior)) @@ -348,7 +359,9 @@ object IorT extends IorTInstances { final def fromIor[F[_]]: FromIorPartiallyApplied[F] = new FromIorPartiallyApplied[F] /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class FromEitherPartiallyApplied[F[_]](private val dummy: Boolean = true) extends AnyVal { def apply[E, A](either: Either[E, A])(implicit F: Applicative[F]): IorT[F, E, A] = @@ -381,7 +394,9 @@ object IorT extends IorTInstances { IorT(F.map(feither)(Ior.fromEither)) /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class FromOptionPartiallyApplied[F[_]](private val dummy: Boolean = true) extends AnyVal { def apply[E, A](option: Option[A], ifNone: => E)(implicit F: Applicative[F]): IorT[F, E, A] = @@ -389,8 +404,8 @@ object IorT extends IorTInstances { } /** - * Transforms an `Option` into an `IorT`, lifted into the specified `Applicative` and using - * the second argument if the `Option` is a `None`. + * Transforms an `Option` into an `IorT`, lifted into the specified `Applicative` and using the second argument if the + * `Option` is a `None`. * {{{ * scala> import cats.data.IorT * scala> import cats.syntax.all._ @@ -430,7 +445,9 @@ object IorT extends IorTInstances { ) /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class CondPartiallyApplied[F[_]](private val dummy: Boolean = true) extends AnyVal { def apply[A, B](test: Boolean, right: => B, left: => A)(implicit F: Applicative[F]): IorT[F, A, B] = @@ -438,8 +455,8 @@ object IorT extends IorTInstances { } /** - * If the condition is satisfied, return the given `B` in `Ior.Right`, otherwise, return the given - * `A` in `Ior.Left`, lifted into the specified `Applicative`. + * If the condition is satisfied, return the given `B` in `Ior.Right`, otherwise, return the given `A` in `Ior.Left`, + * lifted into the specified `Applicative`. * {{{ * scala> import cats.data.IorT * scala> import cats.syntax.all._ @@ -454,8 +471,8 @@ object IorT extends IorTInstances { final def cond[F[_]]: CondPartiallyApplied[F] = new CondPartiallyApplied[F] /** - * If the condition is satisfied, return the value of `IorT.right` on `F[B]`, otherwise, return the - * value of `IorT.left` on `F[A]`. + * If the condition is satisfied, return the value of `IorT.right` on `F[B]`, otherwise, return the value of + * `IorT.left` on `F[A]`. * {{{ * scala> import cats.data.IorT * scala> import cats.syntax.all._ @@ -488,16 +505,12 @@ abstract private[data] class IorTInstances extends IorTInstances1 { new IorTMonoid[F, A, B] { val F0: Monoid[F[Ior[A, B]]] = F } /** - * An alternative [[Parallel]] implementation which merges the semantics of - * the outer Parallel (the F[_] effect) with the effects of the inner - * one (the Ior). The inner Parallel has the semantics of [[Ior]]'s Parallel, - * while the outer has the semantics of parallel ''evaluation'' (in most cases). - * The default Parallel for [[IorT]], when the nested F also has a Parallel, - * is to strictly take the semantics of the nested F and to short-circuit any - * lefts (often, errors) in a left-to-right fashion, mirroring the semantics of - * [[Applicative]] on IorT. This instance is different in that it will not - * ''short-circuit'' but instead accumulate all lefts according to the supplied - * [[Semigroup]]. + * An alternative [[Parallel]] implementation which merges the semantics of the outer Parallel (the F[_] effect) with + * the effects of the inner one (the Ior). The inner Parallel has the semantics of [[Ior]]'s Parallel, while the outer + * has the semantics of parallel ''evaluation'' (in most cases). The default Parallel for [[IorT]], when the nested F + * also has a Parallel, is to strictly take the semantics of the nested F and to short-circuit any lefts (often, + * errors) in a left-to-right fashion, mirroring the semantics of [[Applicative]] on IorT. This instance is different + * in that it will not ''short-circuit'' but instead accumulate all lefts according to the supplied [[Semigroup]]. * * {{{ * implicit val p: Parallel[IorT[IO, Chain[Error], *]] = IorT.accumulatingParallel diff --git a/core/src/main/scala/cats/data/Kleisli.scala b/core/src/main/scala/cats/data/Kleisli.scala index 6bba68ed6e..1da5173113 100644 --- a/core/src/main/scala/cats/data/Kleisli.scala +++ b/core/src/main/scala/cats/data/Kleisli.scala @@ -87,8 +87,8 @@ final case class Kleisli[F[_], -A, B](run: A => F[B]) { self => flatMapF(f) /** - * Tip to tail Kleisli arrow composition. - * Creates a function `A => F[C]` from [[run]] (`A => F[B]`) and the given Kleisli of `B => F[C]`. + * Tip to tail Kleisli arrow composition. Creates a function `A => F[C]` from [[run]] (`A => F[B]`) and the given + * Kleisli of `B => F[C]`. * {{{ * scala> import cats.data.Kleisli, cats.implicits._ * scala> val takeHead = Kleisli[Option, List[Int], Int](_.headOption) @@ -167,19 +167,16 @@ object Kleisli /** * Internal API — shifts the execution of `run` in the `F` context. * - * Used to build Kleisli values for `F[_]` data types that implement `Monad`, - * in which case it is safer to trigger the `F[_]` context earlier. + * Used to build Kleisli values for `F[_]` data types that implement `Monad`, in which case it is safer to trigger the + * `F[_]` context earlier. * - * The requirement is for `FlatMap` as this will get used in operations - * that invoke `F.flatMap` (e.g. in `Kleisli#flatMap`). However we are - * doing discrimination based on inheritance and if we detect an - * `Applicative`, then we use it to trigger the `F[_]` context earlier. + * The requirement is for `FlatMap` as this will get used in operations that invoke `F.flatMap` (e.g. in + * `Kleisli#flatMap`). However we are doing discrimination based on inheritance and if we detect an `Applicative`, + * then we use it to trigger the `F[_]` context earlier. * - * Triggering the `F[_]` context earlier is important to avoid stack - * safety issues for `F` monads that have a stack safe `flatMap` - * implementation. For example `Eval` or `IO`. Without this the `Monad` - * instance is stack unsafe, even if the underlying `F` is stack safe - * in `flatMap`. + * Triggering the `F[_]` context earlier is important to avoid stack safety issues for `F` monads that have a stack + * safe `flatMap` implementation. For example `Eval` or `IO`. Without this the `Monad` instance is stack unsafe, even + * if the underlying `F` is stack safe in `flatMap`. */ private[data] def shift[F[_], A, B](run: A => F[B])(implicit F: FlatMap[F]): Kleisli[F, A, B] = F match { @@ -290,8 +287,8 @@ sealed private[data] trait KleisliFunctions { liftF(F.pure(x)) /** - * Creates a Kleisli arrow which can lift an `A` into applicative context `F`. - * This is distinct from [[pure]] in that the input is what is lifted (and not ignored). + * Creates a Kleisli arrow which can lift an `A` into applicative context `F`. This is distinct from [[pure]] in that + * the input is what is lifted (and not ignored). * {{{ * scala> Kleisli.ask[Option, Int].run(1) * res0: Option[Int]: Some(1) @@ -327,8 +324,7 @@ sealed private[data] trait KleisliFunctions { sealed private[data] trait KleisliFunctionsBinCompat { /** - * Lifts a natural transformation of effects within a Kleisli - * to a transformation of Kleislis. + * Lifts a natural transformation of effects within a Kleisli to a transformation of Kleislis. * * Equivalent to running `mapK(f) on a Kleisli. * @@ -421,8 +417,7 @@ sealed abstract private[data] class KleisliInstances0_5 extends KleisliInstances new KleisliContravariantMonoidal[F, A] { def F: ContravariantMonoidal[F] = F0 } /** - * Witness for: Kleisli[M, E, A] <-> (E, R) => A - * if M is Representable + * Witness for: Kleisli[M, E, A] <-> (E, R) => A if M is Representable */ implicit def catsDataRepresentableForKleisli[M[_], R, E](implicit R: Representable.Aux[M, R], diff --git a/core/src/main/scala/cats/data/Nested.scala b/core/src/main/scala/cats/data/Nested.scala index 24f6aafe6d..d1466825bb 100644 --- a/core/src/main/scala/cats/data/Nested.scala +++ b/core/src/main/scala/cats/data/Nested.scala @@ -25,9 +25,8 @@ package data /** * Similar to [[cats.data.Tuple2K]], but for nested composition. * - * For instance, since both `List` and `Option` have a `Functor`, then so does - * `List[Option[_]]`. This is represented by this data type via the instantiation - * `Nested[List, Option, *]`. + * For instance, since both `List` and `Option` have a `Functor`, then so does `List[Option[_]]`. This is represented by + * this data type via the instantiation `Nested[List, Option, *]`. * * {{{ * scala> import cats.Functor diff --git a/core/src/main/scala/cats/data/Newtype.scala b/core/src/main/scala/cats/data/Newtype.scala index 363d832569..a9444ed647 100644 --- a/core/src/main/scala/cats/data/Newtype.scala +++ b/core/src/main/scala/cats/data/Newtype.scala @@ -23,10 +23,9 @@ package cats package data /** - * Helper trait for `newtype`s. These allow you to create a zero-allocation wrapper around a specific type. - * Similar to `AnyVal` value classes, but never have any runtime overhead. - * It's copied from the newtypes lib by @alexknvl - * For more detail see https://github.com/alexknvl/newtypes + * Helper trait for `newtype`s. These allow you to create a zero-allocation wrapper around a specific type. Similar to + * `AnyVal` value classes, but never have any runtime overhead. It's copied from the newtypes lib by @alexknvl For more + * detail see https://github.com/alexknvl/newtypes */ private[data] trait Newtype { self => private[data] type Base diff --git a/core/src/main/scala/cats/data/Newtype2.scala b/core/src/main/scala/cats/data/Newtype2.scala index 404b80bbde..0993cae245 100644 --- a/core/src/main/scala/cats/data/Newtype2.scala +++ b/core/src/main/scala/cats/data/Newtype2.scala @@ -23,9 +23,8 @@ package cats package data /** - * Helper trait for `newtype`s with two type parameters. - * These allow you to create a zero-allocation wrapper around a specific type. - * Similar to `AnyVal` value classes, but never have any runtime overhead. + * Helper trait for `newtype`s with two type parameters. These allow you to create a zero-allocation wrapper around a + * specific type. Similar to `AnyVal` value classes, but never have any runtime overhead. */ private[data] trait Newtype2 { self => private[data] type Base diff --git a/core/src/main/scala/cats/data/NonEmptyChain.scala b/core/src/main/scala/cats/data/NonEmptyChain.scala index 0e5b10bb4f..54fd6a03f1 100644 --- a/core/src/main/scala/cats/data/NonEmptyChain.scala +++ b/core/src/main/scala/cats/data/NonEmptyChain.scala @@ -30,9 +30,9 @@ import scala.collection.immutable.SortedMap /** * Actual implementation for [[cats.data.NonEmptyChain]] * - * @note This object is kept public for the sake of binary compatibility only - * and therefore is subject to changes in future versions of Cats. - * Do not use directly - use [[cats.data.NonEmptyChain]] instead. + * @note + * This object is kept public for the sake of binary compatibility only and therefore is subject to changes in future + * versions of Cats. Do not use directly - use [[cats.data.NonEmptyChain]] instead. */ object NonEmptyChainImpl extends NonEmptyChainInstances with ScalaVersionSpecificNonEmptyChainImpl { // The following 3 types are components of a technique to @@ -176,9 +176,8 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) prependChain(c) /** - * Yields to Some(a, Chain[A]) with `a` removed where `f` holds for the first time, - * otherwise yields None, if `a` was not found - * Traverses only until `a` is found. + * Yields to Some(a, Chain[A]) with `a` removed where `f` holds for the first time, otherwise yields None, if `a` was + * not found Traverses only until `a` is found. */ final def deleteFirst(f: A => Boolean): Option[(A, Chain[A])] = toChain.deleteFirst(f) @@ -275,14 +274,13 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) final def collect[B](pf: PartialFunction[A, B]): Chain[B] = toChain.collect(pf) /** - * Finds the first element of this `NonEmptyChain` for which the given partial - * function is defined, and applies the partial function to it. + * Finds the first element of this `NonEmptyChain` for which the given partial function is defined, and applies the + * partial function to it. */ final def collectFirst[B](pf: PartialFunction[A, B]): Option[B] = toChain.collectFirst(pf) /** - * Like `collectFirst` from `scala.collection.Traversable` but takes `A => Option[B]` - * instead of `PartialFunction`s. + * Like `collectFirst` from `scala.collection.Traversable` but takes `A => Option[B]` instead of `PartialFunction`s. */ final def collectFirstSome[B](f: A => Option[B]): Option[B] = toChain.collectFirstSome(f) @@ -325,8 +323,8 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) } /** - * Apply `f` to the "initial element" of this chain and lazily combine it - * with every other value using the given function `g`. + * Apply `f` to the "initial element" of this chain and lazily combine it with every other value using the given + * function `g`. * {{{ * scala> import cats.data.NonEmptyChain * scala> val nec = NonEmptyChain(4, 5, 6) @@ -358,8 +356,8 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) } /** - * Apply `f` to the "initial element" of this chain and lazily combine it - * with every other value using the given function `g`. + * Apply `f` to the "initial element" of this chain and lazily combine it with every other value using the given + * function `g`. * {{{ * scala> import cats.data.NonEmptyChain * scala> val nec = NonEmptyChain(4, 5, 6) @@ -412,8 +410,8 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) create(toChain.zipWith(b.toChain)(f)) /** - * Groups elements inside this `NonEmptyChain` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptyChain` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import cats.data.{NonEmptyChain, NonEmptyMap} @@ -447,8 +445,8 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) } /** - * Groups elements inside this `NonEmptyChain` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptyChain` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import cats.data.{NonEmptyChain, NonEmptyMap} @@ -464,10 +462,8 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) groupBy(f) /** - * Groups elements inside this `NonEmptyChain` according to the `Order` - * of the keys produced by the given key function. - * And each element in a group is transformed into a value of type B - * using the mapping function. + * Groups elements inside this `NonEmptyChain` according to the `Order` of the keys produced by the given key + * function. And each element in a group is transformed into a value of type B using the mapping function. * * {{{ * scala> import cats.data.{NonEmptyChain, NonEmptyMap} @@ -483,10 +479,8 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) toChain.groupMap(key)(f).asInstanceOf[NonEmptyMap[K, NonEmptyChain[B]]] /** - * Groups elements inside this `NonEmptyChain` according to the `Order` - * of the keys produced by the given key function. - * And each element in a group is transformed into a value of type B - * using the mapping function. + * Groups elements inside this `NonEmptyChain` according to the `Order` of the keys produced by the given key + * function. And each element in a group is transformed into a value of type B using the mapping function. * * {{{ * scala> import cats.data.{NonEmptyChain, NonEmptyMap} @@ -502,12 +496,9 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) groupMap(key)(f) /** - * Groups elements inside this `NonEmptyChain` according to the `Order` - * of the keys produced by the given key function. - * Then each element in a group is transformed into a value of type B - * using the mapping function. - * And finally they are all reduced into a single value - * using their `Semigroup` + * Groups elements inside this `NonEmptyChain` according to the `Order` of the keys produced by the given key + * function. Then each element in a group is transformed into a value of type B using the mapping function. And + * finally they are all reduced into a single value using their `Semigroup` * * {{{ * scala> import cats.data.{NonEmptyChain, NonEmptyMap} @@ -523,12 +514,9 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) toChain.groupMapReduce(key)(f).asInstanceOf[NonEmptyMap[K, B]] /** - * Groups elements inside this `NonEmptyChain` according to the `Order` - * of the keys produced by the given key function. - * Then each element in a group is transformed into a value of type B - * using the mapping function. - * And finally they are all reduced into a single value - * using their `Semigroup` + * Groups elements inside this `NonEmptyChain` according to the `Order` of the keys produced by the given key + * function. Then each element in a group is transformed into a value of type B using the mapping function. And + * finally they are all reduced into a single value using their `Semigroup` * * {{{ * scala> import cats.data.{NonEmptyChain, NonEmptyMap} @@ -544,12 +532,9 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) groupMapReduce(key)(f) /** - * Groups elements inside this `NonEmptyChain` according to the `Order` - * of the keys produced by the given key function. - * Then each element in a group is transformed into a value of type B - * using the mapping function. - * And finally they are all reduced into a single value - * using the provided combine function. + * Groups elements inside this `NonEmptyChain` according to the `Order` of the keys produced by the given key + * function. Then each element in a group is transformed into a value of type B using the mapping function. And + * finally they are all reduced into a single value using the provided combine function. * * {{{ * scala> import cats.data.{NonEmptyChain, NonEmptyMap} @@ -567,12 +552,9 @@ class NonEmptyChainOps[A](private val value: NonEmptyChain[A]) toChain.groupMapReduceWith(key)(f)(combine).asInstanceOf[NonEmptyMap[K, B]] /** - * Groups elements inside this `NonEmptyChain` according to the `Order` - * of the keys produced by the given key function. - * Then each element in a group is transformed into a value of type B - * using the mapping function. - * And finally they are all reduced into a single value - * using the provided combine function. + * Groups elements inside this `NonEmptyChain` according to the `Order` of the keys produced by the given key + * function. Then each element in a group is transformed into a value of type B using the mapping function. And + * finally they are all reduced into a single value using the provided combine function. * * {{{ * scala> import cats.data.{NonEmptyChain, NonEmptyMap} diff --git a/core/src/main/scala/cats/data/NonEmptyList.scala b/core/src/main/scala/cats/data/NonEmptyList.scala index fb6d4a7aac..68011f20bf 100644 --- a/core/src/main/scala/cats/data/NonEmptyList.scala +++ b/core/src/main/scala/cats/data/NonEmptyList.scala @@ -31,8 +31,7 @@ import scala.collection.mutable import scala.collection.mutable.ListBuffer /** - * A data type which represents a non empty list of A, with - * single element (head) and optional structure (tail). + * A data type which represents a non empty list of A, with single element (head) and optional structure (tail). */ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollection[A, List, NonEmptyList] { @@ -142,7 +141,7 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec /** * Alias for [[prependList]] - * + * * {{{ * scala> import cats.data.NonEmptyList * scala> val nel = NonEmptyList.of(1, 2, 3) @@ -246,8 +245,8 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec } /** - * Builds a new `List` by applying a partial function to - * all the elements from this `NonEmptyList` on which the function is defined + * Builds a new `List` by applying a partial function to all the elements from this `NonEmptyList` on which the + * function is defined * * {{{ * scala> import cats.data.NonEmptyList @@ -336,12 +335,14 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec /** * Right-associative fold on the structure using f. + * {{{ * scala> import cats.data.NonEmptyList * scala> import cats.Eval * scala> import scala.math.pow * scala> val nel = NonEmptyList.of(2,2,2) * scala> (nel.foldRight (Eval.now(1)) ((a, b) => Eval.now(pow(a, b.value).toInt))).value * res0: Int = 16 + * }}} */ def foldRight[B](lb: Eval[B])(f: (A, Eval[B]) => Eval[B]): Eval[B] = Foldable[List].foldRight(toList, lb)(f) @@ -517,8 +518,8 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec NonEmptyList.fromListUnsafe(toList.sorted(AA.toOrdering)) /** - * Groups elements inside this `NonEmptyList` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptyList` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -535,8 +536,8 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec groupMap(key = f)(identity) /** - * Groups elements inside this `NonEmptyList` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptyList` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import cats.data.{NonEmptyList, NonEmptyMap} @@ -552,10 +553,8 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec NonEmptyMap.fromMapUnsafe(groupBy(f)) /** - * Groups elements inside this `NonEmptyList` according to the `Order` - * of the keys produced by the given key function. - * And each element in a group is transformed into a value of type B - * using the mapping function. + * Groups elements inside this `NonEmptyList` according to the `Order` of the keys produced by the given key function. + * And each element in a group is transformed into a value of type B using the mapping function. * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -587,10 +586,8 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec } /** - * Groups elements inside this `NonEmptyList` according to the `Order` - * of the keys produced by the given key function. - * And each element in a group is transformed into a value of type B - * using the mapping function. + * Groups elements inside this `NonEmptyList` according to the `Order` of the keys produced by the given key function. + * And each element in a group is transformed into a value of type B using the mapping function. * * {{{ * scala> import cats.data.{NonEmptyList, NonEmptyMap} @@ -606,12 +603,9 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec NonEmptyMap.fromMapUnsafe(groupMap(key)(f)) /** - * Groups elements inside this `NonEmptyList` according to the `Order` - * of the keys produced by the given key function. - * Then each element in a group is transformed into a value of type B - * using the mapping function. - * And finally they are all reduced into a single value - * using their `Semigroup`. + * Groups elements inside this `NonEmptyList` according to the `Order` of the keys produced by the given key function. + * Then each element in a group is transformed into a value of type B using the mapping function. And finally they are + * all reduced into a single value using their `Semigroup`. * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -628,12 +622,9 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec groupMapReduceWith(key)(f)(B.combine) /** - * Groups elements inside this `NonEmptyList` according to the `Order` - * of the keys produced by the given key function. - * Then each element in a group is transformed into a value of type B - * using the mapping function. - * And finally they are all reduced into a single value - * using their `Semigroup`. + * Groups elements inside this `NonEmptyList` according to the `Order` of the keys produced by the given key function. + * Then each element in a group is transformed into a value of type B using the mapping function. And finally they are + * all reduced into a single value using their `Semigroup`. * * {{{ * scala> import cats.data.{NonEmptyList, NonEmptyMap} @@ -649,12 +640,9 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec NonEmptyMap.fromMapUnsafe(groupMapReduce(key)(f)) /** - * Groups elements inside this `NonEmptyList` according to the `Order` - * of the keys produced by the given key function. - * Then each element in a group is transformed into a value of type B - * using the mapping function. - * And finally they are all reduced into a single value - * using the provided combine function. + * Groups elements inside this `NonEmptyList` according to the `Order` of the keys produced by the given key function. + * Then each element in a group is transformed into a value of type B using the mapping function. And finally they are + * all reduced into a single value using the provided combine function. * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -684,12 +672,9 @@ final case class NonEmptyList[+A](head: A, tail: List[A]) extends NonEmptyCollec } /** - * Groups elements inside this `NonEmptyList` according to the `Order` - * of the keys produced by the given key function. - * Then each element in a group is transformed into a value of type B - * using the mapping function. - * And finally they are all reduced into a single value - * using the provided combine function. + * Groups elements inside this `NonEmptyList` according to the `Order` of the keys produced by the given key function. + * Then each element in a group is transformed into a value of type B using the mapping function. And finally they are + * all reduced into a single value using the provided combine function. * * {{{ * scala> import cats.data.{NonEmptyList, NonEmptyMap} @@ -782,11 +767,10 @@ object NonEmptyList extends NonEmptyListInstances { /** * Create a `NonEmptyList` from a `List`. * - * The result will be `None` if the input list is empty and `Some` wrapping a - * `NonEmptyList` otherwise. + * The result will be `None` if the input list is empty and `Some` wrapping a `NonEmptyList` otherwise. * - * @see [[fromListUnsafe]] for an unsafe version that throws an exception if - * the input list is empty. + * @see + * [[fromListUnsafe]] for an unsafe version that throws an exception if the input list is empty. */ def fromList[A](l: List[A]): Option[NonEmptyList[A]] = l match { @@ -795,11 +779,10 @@ object NonEmptyList extends NonEmptyListInstances { } /** - * Create a `NonEmptyList` from a `List`, or throw an - * `IllegalArgumentException` if the input list is empty. + * Create a `NonEmptyList` from a `List`, or throw an `IllegalArgumentException` if the input list is empty. * - * @see [[fromList]] for a safe version that returns `None` if the input list - * is empty. + * @see + * [[fromList]] for a safe version that returns `None` if the input list is empty. */ def fromListUnsafe[A](l: List[A]): NonEmptyList[A] = l match { diff --git a/core/src/main/scala/cats/data/NonEmptyMapImpl.scala b/core/src/main/scala/cats/data/NonEmptyMapImpl.scala index d817b5bd5c..5754e2e512 100644 --- a/core/src/main/scala/cats/data/NonEmptyMapImpl.scala +++ b/core/src/main/scala/cats/data/NonEmptyMapImpl.scala @@ -29,9 +29,9 @@ import scala.collection.immutable.* /** * Actual implementation for [[cats.data.NonEmptyMap]] * - * @note This object is kept public for the sake of binary compatibility only - * and therefore is subject to changes in future versions of Cats. - * Do not use directly - use [[cats.data.NonEmptyMap]] instead. + * @note + * This object is kept public for the sake of binary compatibility only and therefore is subject to changes in future + * versions of Cats. Do not use directly - use [[cats.data.NonEmptyMap]] instead. */ object NonEmptyMapImpl extends NonEmptyMapInstances with Newtype2 { @@ -216,8 +216,7 @@ sealed class NonEmptyMapOps[K, A](private[data] val value: NonEmptyMap[K, A]) { reduceLeftTo(identity)(f) /** - * Apply `f` to the "initial element" of `fa` and combine it with - * every other value using the given function `g`. + * Apply `f` to the "initial element" of `fa` and combine it with every other value using the given function `g`. */ def reduceLeftTo[B](f: A => B)(g: (B, A) => B): B = tail.foldLeft(f(head._2))((b, a) => g(b, a._2)) @@ -229,8 +228,8 @@ sealed class NonEmptyMapOps[K, A](private[data] val value: NonEmptyMap[K, A]) { reduceRightTo(identity)(f) /** - * Apply `f` to the "initial element" of this map and lazily combine it - * with every other value using the given function `g`. + * Apply `f` to the "initial element" of this map and lazily combine it with every other value using the given + * function `g`. */ def reduceRightTo[B](f: A => B)(g: (A, Eval[B]) => Eval[B]): Eval[B] = Always((head, tail)).flatMap { case ((_, a), ga) => @@ -247,9 +246,8 @@ sealed class NonEmptyMapOps[K, A](private[data] val value: NonEmptyMap[K, A]) { reduceLeft(S.combine) /** - * Given a function which returns a G effect, thread this effect - * through the running of this function on all the values in this map, - * returning an NonEmptyMap[K, B] in a G context. + * Given a function which returns a G effect, thread this effect through the running of this function on all the + * values in this map, returning an NonEmptyMap[K, B] in a G context. */ def nonEmptyTraverse[G[_], B](f: A => G[B])(implicit G: Apply[G]): G[NonEmptyMap[K, B]] = { def loop(h: (K, A), t: SortedMap[K, A]): Eval[G[NonEmptyMap[K, B]]] = @@ -264,9 +262,8 @@ sealed class NonEmptyMapOps[K, A](private[data] val value: NonEmptyMap[K, A]) { /** * Typesafe stringification method. * - * This method is similar to .toString except that it stringifies - * values according to Show[_] instances, rather than using the - * universal .toString method. + * This method is similar to .toString except that it stringifies values according to Show[_] instances, rather than + * using the universal .toString method. */ def show(implicit A: Show[A], K: Show[K]): String = s"NonEmpty${Show[SortedMap[K, A]].show(toSortedMap)}" @@ -274,10 +271,8 @@ sealed class NonEmptyMapOps[K, A](private[data] val value: NonEmptyMap[K, A]) { /** * Typesafe equality operator. * - * This method is similar to == except that it only allows two - * NonEmptySet[A] values to be compared to each other, and uses - * equality provided by Eq[_] instances, rather than using the - * universal equality provided by .equals. + * This method is similar to == except that it only allows two NonEmptySet[A] values to be compared to each other, and + * uses equality provided by Eq[_] instances, rather than using the universal equality provided by .equals. */ def ===(that: NonEmptyMap[K, A])(implicit A: Eq[A]): Boolean = Eq[SortedMap[K, A]].eqv(toSortedMap, that.toSortedMap) diff --git a/core/src/main/scala/cats/data/NonEmptySeq.scala b/core/src/main/scala/cats/data/NonEmptySeq.scala index e67649cb15..fce864722b 100644 --- a/core/src/main/scala/cats/data/NonEmptySeq.scala +++ b/core/src/main/scala/cats/data/NonEmptySeq.scala @@ -30,11 +30,9 @@ import scala.collection.mutable import scala.collection.immutable.{Seq, SortedMap, TreeMap, TreeSet} /** - * A data type which represents a `Seq` guaranteed to contain at least one element. - *
- * Note that the constructor is `private` to prevent accidental construction of an empty - * `NonEmptySeq`. However, due to https://issues.scala-lang.org/browse/SI-6601, on - * Scala 2.10, this may be bypassed due to a compiler bug. + * A data type which represents a `Seq` guaranteed to contain at least one element.
Note that the constructor is + * `private` to prevent accidental construction of an empty `NonEmptySeq`. However, due to + * https://issues.scala-lang.org/browse/SI-6601, on Scala 2.10, this may be bypassed due to a compiler bug. */ final class NonEmptySeq[+A] private (val toSeq: Seq[A]) extends AnyVal with NonEmptyCollection[A, Seq, NonEmptySeq] { @@ -56,8 +54,8 @@ final class NonEmptySeq[+A] private (val toSeq: Seq[A]) extends AnyVal with NonE if (toSeq.isDefinedAt(i)) Some(new NonEmptySeq(toSeq.updated(i, a))) else None /** - * Updates the element at the index, or throws an `IndexOutOfBoundsException` - * if none exists (if `i` does not satisfy `0 <= i < length`). + * Updates the element at the index, or throws an `IndexOutOfBoundsException` if none exists (if `i` does not satisfy + * `0 <= i < length`). */ def updatedUnsafe[AA >: A](i: Int, a: AA): NonEmptySeq[AA] = new NonEmptySeq(toSeq.updated(i, a)) @@ -211,10 +209,8 @@ final class NonEmptySeq[+A] private (val toSeq: Seq[A]) extends AnyVal with NonE /** * Typesafe equality operator. * - * This method is similar to == except that it only allows two - * NonEmptySeq[A] values to be compared to each other, and uses - * equality provided by Eq[_] instances, rather than using the - * universal equality provided by .equals. + * This method is similar to == except that it only allows two NonEmptySeq[A] values to be compared to each other, and + * uses equality provided by Eq[_] instances, rather than using the universal equality provided by .equals. */ def ===[AA >: A](that: NonEmptySeq[AA])(implicit A: Eq[AA]): Boolean = Eq[Seq[AA]].eqv(toSeq, that.toSeq) @@ -222,9 +218,8 @@ final class NonEmptySeq[+A] private (val toSeq: Seq[A]) extends AnyVal with NonE /** * Typesafe stringification method. * - * This method is similar to .toString except that it stringifies - * values according to Show[_] instances, rather than using the - * universal .toString method. + * This method is similar to .toString except that it stringifies values according to Show[_] instances, rather than + * using the universal .toString method. */ def show[AA >: A](implicit AA: Show[AA]): String = s"NonEmptySeq(${toSeq.iterator.map(AA.show).mkString(", ")})" @@ -300,8 +295,8 @@ final class NonEmptySeq[+A] private (val toSeq: Seq[A]) extends AnyVal with NonE new NonEmptySeq(toSeq.sorted(AA.toOrdering)) /** - * Groups elements inside this `NonEmptySeq` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptySeq` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -333,8 +328,8 @@ final class NonEmptySeq[+A] private (val toSeq: Seq[A]) extends AnyVal with NonE } /** - * Groups elements inside this `NonEmptySeq` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptySeq` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import cats.data.{NonEmptyMap, NonEmptySeq} @@ -410,8 +405,8 @@ sealed abstract private[data] class NonEmptySeqInstances { catsDataInstancesForNonEmptySeqBinCompat1 /** - * This is not a bug. The declared type of `catsDataInstancesForNonEmptySeq` intentionally ignores - * `NonEmptyReducible` trait for it not being a typeclass. + * This is not a bug. The declared type of `catsDataInstancesForNonEmptySeq` intentionally ignores `NonEmptyReducible` + * trait for it not being a typeclass. * * Also see the discussion: PR #3541 and issue #3069. */ diff --git a/core/src/main/scala/cats/data/NonEmptySet.scala b/core/src/main/scala/cats/data/NonEmptySet.scala index dff4adb527..33cd141607 100644 --- a/core/src/main/scala/cats/data/NonEmptySet.scala +++ b/core/src/main/scala/cats/data/NonEmptySet.scala @@ -31,9 +31,9 @@ import kernel.compat.scalaVersionSpecific.* /** * Actual implementation for [[cats.data.NonEmptySet]] * - * @note This object is kept public for the sake of binary compatibility only - * and therefore is subject to changes in future versions of Cats. - * Do not use directly - use [[cats.data.NonEmptySet]] instead. + * @note + * This object is kept public for the sake of binary compatibility only and therefore is subject to changes in future + * versions of Cats. Do not use directly - use [[cats.data.NonEmptySet]] instead. */ object NonEmptySetImpl extends NonEmptySetInstances with Newtype { @@ -263,8 +263,8 @@ sealed class NonEmptySetOps[A](private[data] val value: NonEmptySet[A]) { toSortedSet.reduceLeft(f) /** - * Apply `f` to the "initial element" of this set and lazily combine it - * with every other value using the given function `g`. + * Apply `f` to the "initial element" of this set and lazily combine it with every other value using the given + * function `g`. */ def reduceLeftTo[B](f: A => B)(g: (B, A) => B): B = tail.foldLeft(f(head))((b, a) => g(b, a)) @@ -276,8 +276,8 @@ sealed class NonEmptySetOps[A](private[data] val value: NonEmptySet[A]) { reduceRightTo(identity)(f) /** - * Apply `f` to the "initial element" of this set and lazily combine it - * with every other value using the given function `g`. + * Apply `f` to the "initial element" of this set and lazily combine it with every other value using the given + * function `g`. */ def reduceRightTo[B](f: A => B)(g: (A, Eval[B]) => Eval[B]): Eval[B] = Always((head, tail)).flatMap { case (a, ga) => @@ -311,9 +311,8 @@ sealed class NonEmptySetOps[A](private[data] val value: NonEmptySet[A]) { /** * Typesafe stringification method. * - * This method is similar to .toString except that it stringifies - * values according to Show[_] instances, rather than using the - * universal .toString method. + * This method is similar to .toString except that it stringifies values according to Show[_] instances, rather than + * using the universal .toString method. */ def show(implicit A: Show[A]): String = s"NonEmpty${Show[SortedSet[A]].show(toSortedSet)}" @@ -321,10 +320,8 @@ sealed class NonEmptySetOps[A](private[data] val value: NonEmptySet[A]) { /** * Typesafe equality operator. * - * This method is similar to == except that it only allows two - * NonEmptySet[A] values to be compared to each other, and uses - * equality provided by Eq[_] instances, rather than using the - * universal equality provided by .equals. + * This method is similar to == except that it only allows two NonEmptySet[A] values to be compared to each other, and + * uses equality provided by Eq[_] instances, rather than using the universal equality provided by .equals. */ def ===(that: NonEmptySet[A]): Boolean = Eq[SortedSet[A]].eqv(toSortedSet, that.toSortedSet) @@ -358,8 +355,8 @@ sealed class NonEmptySetOps[A](private[data] val value: NonEmptySet[A]) { NonEmptySetImpl.create(cats.compat.SortedSet.zipWithIndex(toSortedSet)) /** - * Groups elements inside this `NonEmptySet` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptySet` according to the `Order` of the keys produced by the given mapping + * function. */ def groupBy[B](f: A => B)(implicit B: Order[B]): NonEmptyMap[B, NonEmptySet[A]] = reduceLeftTo(a => NonEmptyMap.one(f(a), NonEmptySet.one(a))) { (acc, a) => diff --git a/core/src/main/scala/cats/data/NonEmptyVector.scala b/core/src/main/scala/cats/data/NonEmptyVector.scala index b25684f7f2..2590e21f78 100644 --- a/core/src/main/scala/cats/data/NonEmptyVector.scala +++ b/core/src/main/scala/cats/data/NonEmptyVector.scala @@ -31,11 +31,9 @@ import scala.collection.mutable import scala.collection.immutable.{SortedMap, TreeMap, TreeSet, VectorBuilder} /** - * A data type which represents a `Vector` guaranteed to contain at least one element. - *
- * Note that the constructor is `private` to prevent accidental construction of an empty - * `NonEmptyVector`. However, due to https://issues.scala-lang.org/browse/SI-6601, on - * Scala 2.10, this may be bypassed due to a compiler bug. + * A data type which represents a `Vector` guaranteed to contain at least one element.
Note that the constructor + * is `private` to prevent accidental construction of an empty `NonEmptyVector`. However, due to + * https://issues.scala-lang.org/browse/SI-6601, on Scala 2.10, this may be bypassed due to a compiler bug. */ final class NonEmptyVector[+A] private (val toVector: Vector[A]) extends AnyVal @@ -59,8 +57,8 @@ final class NonEmptyVector[+A] private (val toVector: Vector[A]) if (toVector.isDefinedAt(i)) Some(new NonEmptyVector(toVector.updated(i, a))) else None /** - * Updates the element at the index, or throws an `IndexOutOfBoundsException` - * if none exists (if `i` does not satisfy `0 <= i < length`). + * Updates the element at the index, or throws an `IndexOutOfBoundsException` if none exists (if `i` does not satisfy + * `0 <= i < length`). */ def updatedUnsafe[AA >: A](i: Int, a: AA): NonEmptyVector[AA] = new NonEmptyVector(toVector.updated(i, a)) @@ -126,7 +124,7 @@ final class NonEmptyVector[+A] private (val toVector: Vector[A]) /** * Append another `Vector` to this, producing a new `NonEmptyVector` - * + * * {{{ * scala> import cats.data.NonEmptyVector * scala> val nev = NonEmptyVector.of(1, 2, 3) @@ -221,10 +219,8 @@ final class NonEmptyVector[+A] private (val toVector: Vector[A]) /** * Typesafe equality operator. * - * This method is similar to == except that it only allows two - * NonEmptyVector[A] values to be compared to each other, and uses - * equality provided by Eq[_] instances, rather than using the - * universal equality provided by .equals. + * This method is similar to == except that it only allows two NonEmptyVector[A] values to be compared to each other, + * and uses equality provided by Eq[_] instances, rather than using the universal equality provided by .equals. */ def ===[AA >: A](that: NonEmptyVector[AA])(implicit A: Eq[AA]): Boolean = Eq[Vector[AA]].eqv(toVector, that.toVector) @@ -232,9 +228,8 @@ final class NonEmptyVector[+A] private (val toVector: Vector[A]) /** * Typesafe stringification method. * - * This method is similar to .toString except that it stringifies - * values according to Show[_] instances, rather than using the - * universal .toString method. + * This method is similar to .toString except that it stringifies values according to Show[_] instances, rather than + * using the universal .toString method. */ def show[AA >: A](implicit AA: Show[AA]): String = s"NonEmpty${Show[Vector[AA]].show(toVector)}" @@ -293,8 +288,8 @@ final class NonEmptyVector[+A] private (val toVector: Vector[A]) new NonEmptyVector(toVector.sorted(AA.toOrdering)) /** - * Groups elements inside this `NonEmptyVector` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptyVector` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import scala.collection.immutable.SortedMap @@ -326,8 +321,8 @@ final class NonEmptyVector[+A] private (val toVector: Vector[A]) } /** - * Groups elements inside this `NonEmptyVector` according to the `Order` - * of the keys produced by the given mapping function. + * Groups elements inside this `NonEmptyVector` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import cats.data.{NonEmptyMap, NonEmptyVector} diff --git a/core/src/main/scala/cats/data/OneAnd.scala b/core/src/main/scala/cats/data/OneAnd.scala index 8ca9e4bf97..4d9495ed5a 100644 --- a/core/src/main/scala/cats/data/OneAnd.scala +++ b/core/src/main/scala/cats/data/OneAnd.scala @@ -26,9 +26,8 @@ import scala.annotation.tailrec import kernel.compat.scalaVersionSpecific.* /** - * A data type which represents a single element (head) and some other - * structure (tail). As we have done in package.scala, this can be - * used to represent a Stream which is guaranteed to not be empty: + * A data type which represents a single element (head) and some other structure (tail). As we have done in + * package.scala, this can be used to represent a Stream which is guaranteed to not be empty: * * {{{ * type NonEmptyStream[A] = OneAnd[Stream, A] @@ -104,10 +103,8 @@ final case class OneAnd[F[_], A](head: A, tail: F[A]) extends OneAndBinCompat0[F /** * Typesafe equality operator. * - * This method is similar to == except that it only allows two - * OneAnd[F, A] values to be compared to each other, and uses - * equality provided by Eq[_] instances, rather than using the - * universal equality provided by .equals. + * This method is similar to == except that it only allows two OneAnd[F, A] values to be compared to each other, and + * uses equality provided by Eq[_] instances, rather than using the universal equality provided by .equals. */ def ===(that: OneAnd[F, A])(implicit A: Eq[A], FA: Eq[F[A]]): Boolean = A.eqv(head, that.head) && FA.eqv(tail, that.tail) @@ -115,9 +112,8 @@ final case class OneAnd[F[_], A](head: A, tail: F[A]) extends OneAndBinCompat0[F /** * Typesafe stringification method. * - * This method is similar to .toString except that it stringifies - * values according to Show[_] instances, rather than using the - * universal .toString method. + * This method is similar to .toString except that it stringifies values according to Show[_] instances, rather than + * using the universal .toString method. */ def show(implicit A: Show[A], FA: Show[F[A]]): String = s"OneAnd(${A.show(head)}, ${FA.show(tail)})" diff --git a/core/src/main/scala/cats/data/Op.scala b/core/src/main/scala/cats/data/Op.scala index 86bea83cec..01039665de 100644 --- a/core/src/main/scala/cats/data/Op.scala +++ b/core/src/main/scala/cats/data/Op.scala @@ -27,12 +27,11 @@ import cats.arrow.* /** * The dual category of some other category, `Arr`. * - * In a normal category, `Arr` has a direction `A => B`. - * The dual category reverses the direction, making it `B => A`. + * In a normal category, `Arr` has a direction `A => B`. The dual category reverses the direction, making it `B => A`. * - * The dual category can be useful when you want to reason about or define - * operations in terms of their duals without modifying the original category. - * In other words, the dual category provides a "reversed" view to the original category. + * The dual category can be useful when you want to reason about or define operations in terms of their duals without + * modifying the original category. In other words, the dual category provides a "reversed" view to the original + * category. * * Example: * {{{ diff --git a/core/src/main/scala/cats/data/OptionT.scala b/core/src/main/scala/cats/data/OptionT.scala index c7e57b5829..6d0839cbbb 100644 --- a/core/src/main/scala/cats/data/OptionT.scala +++ b/core/src/main/scala/cats/data/OptionT.scala @@ -23,8 +23,8 @@ package cats package data /** - * `OptionT[F[_], A]` is a light wrapper on an `F[Option[A]]` with some - * convenient methods for working with this nested structure. + * `OptionT[F[_], A]` is a light wrapper on an `F[Option[A]]` with some convenient methods for working with this nested + * structure. * * It may also be said that `OptionT` is a monad transformer for `Option`. * @@ -51,16 +51,14 @@ final case class OptionT[F[_], A](value: F[Option[A]]) { F.flatMap(value)(_.fold(default)(f)) /** - * Transform this `OptionT[F, A]` into a `F[Unit]`. - * This is identical to `foldF(F.unit)(f)`. + * Transform this `OptionT[F, A]` into a `F[Unit]`. This is identical to `foldF(F.unit)(f)`. */ def foreachF(f: A => F[Unit])(implicit F: Monad[F]): F[Unit] = foldF(F.unit)(f) /** - * Catamorphism on the Option. This is identical to [[fold]], but it only has - * one parameter list, which can result in better type inference in some - * contexts. + * Catamorphism on the Option. This is identical to [[fold]], but it only has one parameter list, which can result in + * better type inference in some contexts. * * Example: * {{{ @@ -75,9 +73,8 @@ final case class OptionT[F[_], A](value: F[Option[A]]) { fold(default)(f) /** - * Effectful catamorphism on the Option. This is identical to [[foldF]], but it only has - * one parameter list, which can result in better type inference in some - * contexts. + * Effectful catamorphism on the Option. This is identical to [[foldF]], but it only has one parameter list, which can + * result in better type inference in some contexts. * * Example: * {{{ @@ -138,12 +135,12 @@ final case class OptionT[F[_], A](value: F[Option[A]]) { /** * Modify the context `F` using transformation `f`. - * + * * Example: * {{{ * scala> import cats.~> * scala> import cats.data.OptionT - * + * * scala> val optionToList: Option ~> List = new ~>[Option, List] { override def apply[A](o: Option[A]): List[A] = o.toList } * scala> val optionT: OptionT[Option, Int] = OptionT.some(42) * scala> optionT.mapK[List](optionToList) @@ -259,9 +256,9 @@ final case class OptionT[F[_], A](value: F[Option[A]]) { transform(_.flatMap(f)) /** - * Perform an effect if the value inside the is a `None`, leaving the value untouched. Equivalent to [[orElseF]] - * with an effect returning `None` as argument. - * + * Perform an effect if the value inside the is a `None`, leaving the value untouched. Equivalent to [[orElseF]] with + * an effect returning `None` as argument. + * * Example: * {{{ * scala> import cats.data.OptionT @@ -303,9 +300,9 @@ final case class OptionT[F[_], A](value: F[Option[A]]) { /** * Like [[getOrElseF]] but accept an error `E` and raise it when the inner `Option` is `None` - * + * * Equivalent to `getOrElseF(F.raiseError(e)))` - * + * * {{{ * scala> import cats.data.OptionT * scala> import scala.util.{Success, Try} @@ -380,8 +377,7 @@ final case class OptionT[F[_], A](value: F[Option[A]]) { }) /** - * It is used for desugaring 'for comprehensions'. OptionT wouldn't work in 'for-comprehensions' without - * this method. + * It is used for desugaring 'for comprehensions'. OptionT wouldn't work in 'for-comprehensions' without this method. * Example: * {{{ * scala> import cats.data.OptionT @@ -656,9 +652,9 @@ final case class OptionT[F[_], A](value: F[Option[A]]) { /** * Transform this `OptionT[F, A]` into a `[[Nested]][F, Option, A]`. * - * An example where `toNested` can be used, is to get the `Apply.ap` function with the - * behavior from the composed `Apply` instances from `F` and `Option`, which is - * inconsistent with the behavior of the `ap` from `Monad` of `OptionT`. + * An example where `toNested` can be used, is to get the `Apply.ap` function with the behavior from the composed + * `Apply` instances from `F` and `Option`, which is inconsistent with the behavior of the `ap` from `Monad` of + * `OptionT`. * * {{{ * scala> import cats.data.OptionT @@ -678,7 +674,9 @@ final case class OptionT[F[_], A](value: F[Option[A]]) { object OptionT extends OptionTInstances { /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class PurePartiallyApplied[F[_]](private val dummy: Boolean = true) extends AnyVal { def apply[A](value: A)(implicit F: Applicative[F]): OptionT[F, A] = @@ -720,7 +718,9 @@ object OptionT extends OptionTInstances { def fromOption[F[_]]: FromOptionPartiallyApplied[F] = new FromOptionPartiallyApplied /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class FromOptionPartiallyApplied[F[_]](private val dummy: Boolean = true) extends AnyVal { def apply[A](value: Option[A])(implicit F: Applicative[F]): OptionT[F, A] = @@ -746,22 +746,22 @@ object OptionT extends OptionTInstances { new (F ~> OptionT[F, *]) { def apply[A](a: F[A]): OptionT[F, A] = OptionT.liftF(a) } /** - * Creates a non-empty `OptionT[F, A]` from an `A` value if the given condition is `true`. - * Otherwise, `none[F, A]` is returned. Analogous to `Option.when`. + * Creates a non-empty `OptionT[F, A]` from an `A` value if the given condition is `true`. Otherwise, `none[F, A]` is + * returned. Analogous to `Option.when`. */ def when[F[_], A](cond: Boolean)(a: => A)(implicit F: Applicative[F]): OptionT[F, A] = if (cond) OptionT.some[F](a) else OptionT.none[F, A] /** - * Creates a non-empty `OptionT[F, A]` from an `F[A]` value if the given condition is `true`. - * Otherwise, `none[F, A]` is returned. Analogous to `Option.when`. + * Creates a non-empty `OptionT[F, A]` from an `F[A]` value if the given condition is `true`. Otherwise, `none[F, A]` + * is returned. Analogous to `Option.when`. */ def whenF[F[_], A](cond: Boolean)(fa: => F[A])(implicit F: Applicative[F]): OptionT[F, A] = if (cond) OptionT.liftF(fa) else OptionT.none[F, A] /** - * Creates a non-empty `OptionT[F, A]` from an `F[A]` value if the given F-condition is considered `true`. - * Otherwise, `none[F, A]` is returned. Analogous to `Option.when` but for effectful conditions. + * Creates a non-empty `OptionT[F, A]` from an `F[A]` value if the given F-condition is considered `true`. Otherwise, + * `none[F, A]` is returned. Analogous to `Option.when` but for effectful conditions. */ def whenM[F[_], A](cond: F[Boolean])(fa: => F[A])(implicit F: Monad[F]): OptionT[F, A] = OptionT( F.ifM(cond)(ifTrue = F.map(fa)(Some(_)), ifFalse = F.pure(None)) @@ -774,22 +774,22 @@ object OptionT extends OptionTInstances { new (F ~> OptionT[F, *]) { def apply[A](a: F[A]): OptionT[F, A] = OptionT.whenF(cond)(a) } /** - * Creates a non-empty `OptionT[F, A]` from an `A` if the given condition is `false`. - * Otherwise, `none[F, A]` is returned. Analogous to `Option.unless`. + * Creates a non-empty `OptionT[F, A]` from an `A` if the given condition is `false`. Otherwise, `none[F, A]` is + * returned. Analogous to `Option.unless`. */ def unless[F[_], A](cond: Boolean)(a: => A)(implicit F: Applicative[F]): OptionT[F, A] = OptionT.when(!cond)(a) /** - * Creates an non-empty `OptionT[F, A]` from an `F[A]` if the given condition is `false`. - * Otherwise, `none[F, A]` is returned. Analogous to `Option.unless`. + * Creates an non-empty `OptionT[F, A]` from an `F[A]` if the given condition is `false`. Otherwise, `none[F, A]` is + * returned. Analogous to `Option.unless`. */ def unlessF[F[_], A](cond: Boolean)(fa: => F[A])(implicit F: Applicative[F]): OptionT[F, A] = OptionT.whenF(!cond)(fa) /** - * Creates a non-empty `OptionT[F, A]` from an `F[A]` value if the given F-condition is considered `false`. - * Otherwise, `none[F, A]` is returned. Analogous to `Option.unless` but for effectful conditions. + * Creates a non-empty `OptionT[F, A]` from an `F[A]` value if the given F-condition is considered `false`. Otherwise, + * `none[F, A]` is returned. Analogous to `Option.unless` but for effectful conditions. */ def unlessM[F[_], A](cond: F[Boolean])(fa: => F[A])(implicit F: Monad[F]): OptionT[F, A] = OptionT( F.ifM(cond)(ifTrue = F.pure(None), ifFalse = F.map(fa)(Some(_))) diff --git a/core/src/main/scala/cats/data/RepresentableStore.scala b/core/src/main/scala/cats/data/RepresentableStore.scala index 867e1dff40..f49325fc64 100644 --- a/core/src/main/scala/cats/data/RepresentableStore.scala +++ b/core/src/main/scala/cats/data/RepresentableStore.scala @@ -24,8 +24,8 @@ package cats.data import cats.{Comonad, Functor, Representable} /** - * A generalization of `StoreT`, where the underlying functor `F` has a `Representable` instance. - * `Store` is the dual of `State` + * A generalization of `StoreT`, where the underlying functor `F` has a `Representable` instance. `Store` is the dual of + * `State` */ final case class RepresentableStore[F[_], S, A](fa: F[A], index: S)(implicit R: Representable.Aux[F, S]) { @@ -35,8 +35,7 @@ final case class RepresentableStore[F[_], S, A](fa: F[A], index: S)(implicit R: def peek(s: S): A = R.index(fa)(s) /** - * Peek at what the focus would be if the current focus where transformed - * with the given function. + * Peek at what the focus would be if the current focus where transformed with the given function. */ def peeks(f: S => S): A = peek(f(index)) @@ -56,15 +55,14 @@ final case class RepresentableStore[F[_], S, A](fa: F[A], index: S)(implicit R: lazy val extract: A = peek(index) /** - * `coflatten` is the dual of `flatten` on `FlatMap`. Whereas flatten removes - * a layer of `F`, coflatten adds a layer of `F` + * `coflatten` is the dual of `flatten` on `FlatMap`. Whereas flatten removes a layer of `F`, coflatten adds a layer + * of `F` */ lazy val coflatten: RepresentableStore[F, S, RepresentableStore[F, S, A]] = RepresentableStore(R.tabulate(idx => RepresentableStore(fa, idx)), index) /** - * `coflatMap` is the dual of `flatMap` on `FlatMap`. It applies - * a value in a context to a function that takes a value + * `coflatMap` is the dual of `flatMap` on `FlatMap`. It applies a value in a context to a function that takes a value * in a context and returns a normal value. */ def coflatMap[B](f: RepresentableStore[F, S, A] => B): RepresentableStore[F, S, B] = diff --git a/core/src/main/scala/cats/data/RepresentableStoreT.scala b/core/src/main/scala/cats/data/RepresentableStoreT.scala index a0430c7e2c..921f5a2b62 100644 --- a/core/src/main/scala/cats/data/RepresentableStoreT.scala +++ b/core/src/main/scala/cats/data/RepresentableStoreT.scala @@ -43,8 +43,7 @@ final case class RepresentableStoreT[W[_], F[_], S, A](runF: W[F[A]], index: S)( def peek(s: S)(implicit W: Comonad[W]): A = W.extract(W.map(runF)(fa => F.index(fa)(s))) /** - * Peek at what the focus would be if the current focus where transformed - * with the given function. + * Peek at what the focus would be if the current focus where transformed with the given function. */ def peeks(f: S => S)(implicit W: Comonad[W]): A = peek(f(index)) @@ -64,8 +63,7 @@ final case class RepresentableStoreT[W[_], F[_], S, A](runF: W[F[A]], index: S)( def extract(implicit W: Comonad[W]): A = peek(index) /** - * `coflatMap` is the dual of `flatMap` on `FlatMap`. It applies - * a value in a context to a function that takes a value + * `coflatMap` is the dual of `flatMap` on `FlatMap`. It applies a value in a context to a function that takes a value * in a context and returns a normal value. */ def coflatMap[B](f: RepresentableStoreT[W, F, S, A] => B)(implicit W: Comonad[W]): RepresentableStoreT[W, F, S, B] = @@ -75,8 +73,8 @@ final case class RepresentableStoreT[W[_], F[_], S, A](runF: W[F[A]], index: S)( ) /** - * `coflatten` is the dual of `flatten` on `FlatMap`. Whereas flatten removes - * a layer of `F`, coflatten adds a layer of `F` + * `coflatten` is the dual of `flatten` on `FlatMap`. Whereas flatten removes a layer of `F`, coflatten adds a layer + * of `F` */ def coflatten(implicit W: Comonad[W]): RepresentableStoreT[W, F, S, RepresentableStoreT[W, F, S, A]] = RepresentableStoreT( diff --git a/core/src/main/scala/cats/data/StrictConstFunction1.scala b/core/src/main/scala/cats/data/StrictConstFunction1.scala index 8d3b9c203b..8b70423447 100644 --- a/core/src/main/scala/cats/data/StrictConstFunction1.scala +++ b/core/src/main/scala/cats/data/StrictConstFunction1.scala @@ -22,18 +22,24 @@ package cats package data -/** A `Function1` with constant value and strictly evaluated combinators. Not suitable - * for composing with side-effecting functions. */ +/** + * A `Function1` with constant value and strictly evaluated combinators. Not suitable for composing with side-effecting + * functions. + */ final private[data] case class StrictConstFunction1[A](a: A) extends Function1[Any, A] { def apply(arg: Any): A = a - /** Creates a new `StrictConstFunction1` by applying `g` to this function's constant value. - * `g` will not be evaluated when the resulting function is subsequently run. Not stack-safe. */ + /** + * Creates a new `StrictConstFunction1` by applying `g` to this function's constant value. `g` will not be evaluated + * when the resulting function is subsequently run. Not stack-safe. + */ override def andThen[B](g: A => B): Any => B = g match { case g: StrictConstFunction1[B] => g case _ => StrictConstFunction1(g(a)) } - /** This is a no-op; `g` will never be used. */ + /** + * This is a no-op; `g` will never be used. + */ override def compose[A0](g: A0 => Any): A0 => A = this } diff --git a/core/src/main/scala/cats/data/Validated.scala b/core/src/main/scala/cats/data/Validated.scala index 199b363797..c8c1994911 100644 --- a/core/src/main/scala/cats/data/Validated.scala +++ b/core/src/main/scala/cats/data/Validated.scala @@ -116,7 +116,8 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Return the Valid value, or the result of f if Invalid + * Return the `Valid` value, or the result of `f` if Invalid + * * Example: * {{{ * scala> import cats.syntax.all._ @@ -184,9 +185,9 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Return this if it is Valid, or else fall back to the given default. - * The functionality is similar to that of [[findValid]] except for failure accumulation, - * where here only the error on the right is preserved and the error on the left is ignored. + * Return this if it is Valid, or else fall back to the given default. The functionality is similar to that of + * [[findValid]] except for failure accumulation, where here only the error on the right is preserved and the error on + * the left is ignored. * * Example: * {{{ @@ -210,8 +211,8 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * If `this` is valid return `this`, otherwise if `that` is valid return `that`, otherwise combine the failures. - * This is similar to [[orElse]] except that here failures are accumulated. + * If `this` is valid return `this`, otherwise if `that` is valid return `that`, otherwise combine the failures. This + * is similar to [[orElse]] except that here failures are accumulated. * * Example: * {{{ @@ -312,8 +313,7 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Convert this value to a single element List if it is Valid, - * otherwise return an empty List + * Convert this value to a single element `List` if it is `Valid`, otherwise return an empty `List` * * Example: * {{{ @@ -336,7 +336,7 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Lift the Invalid value into a NonEmptyList. + * Lift the `Invalid` value into a `NonEmptyList`. * * Example: * {{{ @@ -382,8 +382,8 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Convert to an Either, apply a function, convert back. This is handy - * when you want to use the Monadic properties of the Either type. + * Convert to an `Either`, apply a function, convert back. This is handy when you want to use the Monadic properties + * of the `Either` type. * * Example: * {{{ @@ -403,8 +403,7 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { Validated.fromEither(f(toEither)) /** - * Validated is a [[Bifunctor]], this method applies one of the - * given functions.] + * `Validated` is a [[Bifunctor]], this method applies one of the given functions.] * * Example: * {{{ @@ -499,8 +498,7 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * From Apply: - * if both the function and this value are Valid, apply the function + * From `Apply`: if both the function and this value are `Valid`, apply the function * * Example: * {{{ @@ -581,8 +579,8 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Apply a function to an Invalid value, returning a new Invalid value. - * Or, if the original valid was Valid, return it. + * Apply a function to an `Invalid` value, returning a new `Invalid` value. Or, if the original valid was `Valid`, + * return it. * * Example: * {{{ @@ -606,9 +604,8 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * When Valid, apply the function, marking the result as valid - * inside the Applicative's context, - * when Invalid, lift the Error into the Applicative's context + * When `Valid`, apply the function, marking the result as valid inside the `Applicative`'s context, when `Invalid`, + * lift the Error into the `Applicative`'s context * * Example: * {{{ @@ -640,8 +637,7 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * apply the given function to the value with the given B when - * valid, otherwise return the given B + * Apply the given function to the value with the given B when valid, otherwise return the given B * * Example: * {{{ @@ -664,8 +660,7 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Lazily-apply the given function to the value with the given B - * when valid, otherwise return the given B. + * Lazily-apply the given function to the value with the given `B` when valid, otherwise return the given `B`. * * Example: * {{{ @@ -695,17 +690,13 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Apply a function (that returns a `Validated`) in the valid case. - * Otherwise return the original `Validated`. + * Apply a function (that returns a `Validated`) in the valid case. Otherwise return the original `Validated`. * - * This allows "chained" validation: the output of one validation can be fed - * into another validation function. + * This allows "chained" validation: the output of one validation can be fed into another validation function. * - * This function is similar to `flatMap` on `Either`. It's not called `flatMap`, - * because by Cats convention, `flatMap` is a monadic bind that is consistent - * with `ap`. This method is not consistent with [[ap]] (or other - * `Apply`-based methods), because it has "fail-fast" behavior as opposed to - * accumulating validation failures. + * This function is similar to `flatMap` on `Either`. It's not called `flatMap`, because by Cats convention, `flatMap` + * is a monadic bind that is consistent with `ap`. This method is not consistent with [[ap]] (or other `Apply`-based + * methods), because it has "fail-fast" behavior as opposed to accumulating validation failures. * * Example: * {{{ @@ -729,9 +720,8 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Combine this `Validated` with another `Validated`, using the `Semigroup` - * instances of the underlying `E` and `A` instances. The resultant `Validated` - * will be `Valid`, if, and only if, both this `Validated` instance and the + * Combine this `Validated` with another `Validated`, using the `Semigroup` instances of the underlying `E` and `A` + * instances. The resultant `Validated` will be `Valid`, if, and only if, both this `Validated` instance and the * supplied `Validated` instance are also `Valid`. * * Example: @@ -806,9 +796,8 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Ensure that a successful result passes the given predicate, - * falling back to an Invalid of `onFailure` if the predicate - * returns false. + * Ensure that a successful result passes the given predicate, falling back to an Invalid of `onFailure` if the + * predicate returns false. * * For example: * {{{ @@ -823,9 +812,8 @@ sealed abstract class Validated[+E, +A] extends Product with Serializable { } /** - * Ensure that a successful result passes the given predicate, - * falling back to the an Invalid of the result of `onFailure` if the predicate - * returns false. + * Ensure that a successful result passes the given predicate, falling back to the an Invalid of the result of + * `onFailure` if the predicate returns false. * * For example: * {{{ @@ -856,14 +844,15 @@ object Validated extends ValidatedInstances with ValidatedFunctions with Validat * res0: Validated[NumberFormatException, Int] = Invalid(java.lang.NumberFormatException: For input string: "foo") * }}} * - * This method and its usage of [[NotNull]] are inspired by and derived from - * the `fromTryCatchThrowable` method [[https://github.com/scalaz/scalaz/pull/746/files contributed]] - * to Scalaz by Brian McKenna. + * This method and its usage of [[NotNull]] are inspired by and derived from the `fromTryCatchThrowable` method + * [[https://github.com/scalaz/scalaz/pull/746/files contributed]] to Scalaz by Brian McKenna. */ def catchOnly[T >: Null <: Throwable]: CatchOnlyPartiallyApplied[T] = new CatchOnlyPartiallyApplied[T] /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[data] class CatchOnlyPartiallyApplied[T](private val dummy: Boolean = true) extends AnyVal { /* Note: the NT parameter is not referenced at runtime, but serves a compile-time role. @@ -1183,8 +1172,8 @@ private[data] trait ValidatedFunctions { def fromEither[A, B](e: Either[A, B]): Validated[A, B] = e.fold(invalid, valid) /** - * Converts an `Option[B]` to a `Validated[A, B]`, where the provided `ifNone` values is returned on - * the invalid of the `Validated` when the specified `Option` is `None`. + * Converts an `Option[B]` to a `Validated[A, B]`, where the provided `ifNone` values is returned on the invalid of + * the `Validated` when the specified `Option` is `None`. */ def fromOption[A, B](o: Option[B], ifNone: => A): Validated[A, B] = o.fold(invalid[A, B](ifNone))(valid) @@ -1194,15 +1183,13 @@ private[data] trait ValidatedFunctions { def fromIor[A, B](ior: Ior[A, B]): Validated[A, B] = ior.fold(invalid, valid, (_, b) => valid(b)) /** - * If the condition is satisfied, return the given `A` as valid, - * otherwise return the given `E` as invalid. + * If the condition is satisfied, return the given `A` as valid, otherwise return the given `E` as invalid. */ final def cond[E, A](test: Boolean, a: => A, e: => E): Validated[E, A] = if (test) valid(a) else invalid(e) /** - * If the condition is satisfied, return the given `A` as valid NEL, - * otherwise return the given `E` as invalid NEL. + * If the condition is satisfied, return the given `A` as valid NEL, otherwise return the given `E` as invalid NEL. */ final def condNel[E, A](test: Boolean, a: => A, e: => E): ValidatedNel[E, A] = if (test) validNel(a) else invalidNel(e) @@ -1238,8 +1225,7 @@ private[data] trait ValidatedFunctionsBinCompat0 { def invalidNec[A, B](a: A): ValidatedNec[A, B] = Validated.Invalid(NonEmptyChain.one(a)) /** - * If the condition is satisfied, return the given `B` as valid NEC, - * otherwise return the given `A` as invalid NEC. + * If the condition is satisfied, return the given `B` as valid NEC, otherwise return the given `A` as invalid NEC. */ final def condNec[A, B](test: Boolean, b: => B, a: => A): ValidatedNec[A, B] = if (test) validNec(b) else invalidNec(a) diff --git a/core/src/main/scala/cats/data/package.scala b/core/src/main/scala/cats/data/package.scala index d5c87de18d..d959057d47 100644 --- a/core/src/main/scala/cats/data/package.scala +++ b/core/src/main/scala/cats/data/package.scala @@ -68,9 +68,8 @@ package object data extends ScalaVersionSpecificPackage { object IndexedState extends IndexedStateFunctions /** - * `StateT[F, S, A]` is similar to `Kleisli[F, S, A]` in that it takes an `S` - * argument and produces an `A` value wrapped in `F`. However, it also produces - * an `S` value representing the updated state (which is wrapped in the `F` + * `StateT[F, S, A]` is similar to `Kleisli[F, S, A]` in that it takes an `S` argument and produces an `A` value + * wrapped in `F`. However, it also produces an `S` value representing the updated state (which is wrapped in the `F` * context along with the `A` value. */ type StateT[F[_], S, A] = IndexedStateT[F, S, S, A] @@ -83,8 +82,8 @@ package object data extends ScalaVersionSpecificPackage { val IRWST = IndexedReaderWriterStateT /** - * Represents a stateful computation in a context `F[_]`, over state `S`, with an - * initial environment `E`, an accumulated log `L` and a result `A`. + * Represents a stateful computation in a context `F[_]`, over state `S`, with an initial environment `E`, an + * accumulated log `L` and a result `A`. */ type ReaderWriterStateT[F[_], E, L, S, A] = IndexedReaderWriterStateT[F, E, L, S, S, A] object ReaderWriterStateT extends RWSTFunctions diff --git a/core/src/main/scala/cats/evidence/As.scala b/core/src/main/scala/cats/evidence/As.scala index 7b91e7f774..5186ced6a3 100644 --- a/core/src/main/scala/cats/evidence/As.scala +++ b/core/src/main/scala/cats/evidence/As.scala @@ -27,26 +27,23 @@ import arrow.Category /** * As substitutability: A better `<:<` * - * This class exists to aid in the capture proof of subtyping - * relationships, which can be applied in other context to widen other - * type + * This class exists to aid in the capture proof of subtyping relationships, which can be applied in other context to + * widen other type * - * `A As B` holds whenever `A` could be used in any negative context - * that expects a `B`. (e.g. if you could pass an `A` into any - * function that expects a `B` as input.) + * `A As B` holds whenever `A` could be used in any negative context that expects a `B`. (e.g. if you could pass an `A` + * into any function that expects a `B` as input.) * * This code was ported directly from scalaz to cats using this version from scalaz: * https://github.com/scalaz/scalaz/blob/a89b6d63/core/src/main/scala/scalaz/Liskov.scala * - * The original contribution to scalaz came from Jason Zaugg + * The original contribution to scalaz came from Jason Zaugg */ sealed abstract class As[-A, +B] extends Serializable { /** - * Use this subtyping relationship to replace B with a value of type - * A in a contravariant context. This would commonly be the input - * to a function, such as F in: `type F[-B] = B => String`. In this - * case, we could use A As B to turn an F[B] Into F[A]. + * Use this subtyping relationship to replace B with a value of type A in a contravariant context. This would commonly + * be the input to a function, such as F in: `type F[-B] = B => String`. In this case, we could use A As B to turn an + * F[B] Into F[A]. */ def substitute[F[-_]](p: F[B]): F[A] @@ -57,8 +54,7 @@ sealed abstract class As[-A, +B] extends Serializable { @inline final def coerce(a: A): B = As.witness(this)(a) /** - * A value `A As B` is always sufficient to produce a similar `Predef.<:<` - * value. + * A value `A As B` is always sufficient to produce a similar `Predef.<:<` value. */ @inline final def toPredef: A <:< B = { type F[-Z] = <:<[Z, B] @@ -82,8 +78,7 @@ sealed abstract class AsInstances { object As extends AsInstances with AsSupport { /** - * In truth, "all values of `A Is B` are `refl`". `reflAny` is that - * single value. + * In truth, "all values of `A Is B` are `refl`". `reflAny` is that single value. */ private[this] val reflAny = new (Any As Any) { def substitute[F[-_]](fa: F[Any]) = fa @@ -117,9 +112,8 @@ object As extends AsInstances with AsSupport { @inline def reify[A, B >: A]: A As B = refl /** - * It can be convenient to convert a <:< value into a `<~<` value. - * This is not actually unsafe, but was previously labeled as such out - * of an abundance of caution + * It can be convenient to convert a <:< value into a `<~<` value. This is not actually unsafe, but was previously + * labeled as such out of an abundance of caution */ def fromPredef[A, B](eq: A <:< B): A As B = asFromPredef(eq) @@ -142,8 +136,7 @@ object As extends AsInstances with AsSupport { } /** - * Widen a F[X,+A] to a F[X,B] if (A As B). This can be used to widen - * the output of a Function1, for example. + * Widen a F[X,+A] to a F[X,B] if (A As B). This can be used to widen the output of a Function1, for example. */ def co2_2[T[_, +_], Z, A, B](a: B As Z): T[A, B] As T[A, Z] = { type L[-α] = T[A, α] As T[A, Z] @@ -171,8 +164,7 @@ object As extends AsInstances with AsSupport { def onF[X, A, B](ev: A As B)(fa: X => A): X => B = co2_2[Function1, B, X, A](ev).coerce(fa) /** - * widen two types for binary type constructors covariant in both - * parameters + * widen two types for binary type constructors covariant in both parameters * * lift2(a,b) = co1_2(a) compose co2_2(b) */ @@ -186,11 +178,9 @@ object As extends AsInstances with AsSupport { } /** - * We can lift a subtyping relationship into a contravariant type - * constructor. + * We can lift a subtyping relationship into a contravariant type constructor. * - * Given that F has the shape: F[-_], we show that: - * (A As B) implies (F[B] As F[A]) + * Given that F has the shape: F[-_], we show that: (A As B) implies (F[B] As F[A]) */ def contra[T[-_], A, B](a: A As B): T[B] As T[A] = { type L[-α] = T[B] As T[α] diff --git a/core/src/main/scala/cats/evidence/Is.scala b/core/src/main/scala/cats/evidence/Is.scala index c02a8e314e..794b4fff4f 100644 --- a/core/src/main/scala/cats/evidence/Is.scala +++ b/core/src/main/scala/cats/evidence/Is.scala @@ -25,71 +25,61 @@ import cats.Id import cats.arrow.* /** - * A value of `A Is B` is proof that the types `A` and `B` are the same. More - * powerfully, it asserts that they have the same meaning in all type - * contexts. This can be a more powerful assertion than `A =:= B` and is more - * easily used in manipulation of types while avoiding (potentially - * erroneous) coercions. + * A value of `A Is B` is proof that the types `A` and `B` are the same. More powerfully, it asserts that they have the + * same meaning in all type contexts. This can be a more powerful assertion than `A =:= B` and is more easily used in + * manipulation of types while avoiding (potentially erroneous) coercions. * * `A Is B` is also known as Leibniz equality. */ abstract class Is[A, B] extends Serializable { /** - * To create an instance of `A Is B` you must show that for every choice - * of `F[_]` you can convert `F[A]` to `F[B]`. Loosely, this reads as - * saying that `B` must have the same effect as `A` in all contexts - * therefore allowing type substitution. + * To create an instance of `A Is B` you must show that for every choice of `F[_]` you can convert `F[A]` to `F[B]`. + * Loosely, this reads as saying that `B` must have the same effect as `A` in all contexts therefore allowing type + * substitution. */ def substitute[F[_]](fa: F[A]): F[B] /** - * `Is` is transitive and therefore values of `Is` can be composed in a - * chain much like functions. See also `compose`. + * `Is` is transitive and therefore values of `Is` can be composed in a chain much like functions. See also `compose`. */ @inline final def andThen[C](next: B Is C): A Is C = next.substitute[Is[A, *]](this) /** - * `Is` is transitive and therefore values of `Is` can be composed in a - * chain much like functions. See also `andThen`. + * `Is` is transitive and therefore values of `Is` can be composed in a chain much like functions. See also `andThen`. */ @inline final def compose[C](prev: C Is A): C Is B = prev.andThen(this) /** - * `Is` is symmetric and therefore can be flipped around. Flipping is its - * own inverse, so `x.flip.flip == x`. + * `Is` is symmetric and therefore can be flipped around. Flipping is its own inverse, so `x.flip.flip == x`. */ @inline final def flip: B Is A = this.substitute[Is[*, A]](Is.refl) /** - * Sometimes for more complex substitutions it helps the typechecker to - * wrap one layer of `F[_]` context around the types you're equating - * before substitution. + * Sometimes for more complex substitutions it helps the typechecker to wrap one layer of `F[_]` context around the + * types you're equating before substitution. */ @inline final def lift[F[_]]: F[A] Is F[B] = substitute[λ[α => F[A] Is F[α]]](Is.refl) /** - * Substitution on identity brings about a direct coercion function of the - * same form that `=:=` provides. + * Substitution on identity brings about a direct coercion function of the same form that `=:=` provides. */ @inline final def coerce(a: A): B = substitute[Id](a) /** - * A value `A Is B` is always sufficient to produce a similar `Predef.=:=` - * value. + * A value `A Is B` is always sufficient to produce a similar `Predef.=:=` value. */ @deprecated("Use toPredef for consistency with As", "2.2.0") @inline final def predefEq: A =:= B = substitute[=:=[A, *]](implicitly[A =:= A]) /** - * A value `A Is B` is always sufficient to produce a similar `Predef.=:=` - * value. + * A value `A Is B` is always sufficient to produce a similar `Predef.=:=` value. */ @inline final def toPredef: A =:= B = substitute[=:=[A, *]](implicitly[A =:= A]) @@ -110,29 +100,26 @@ sealed abstract class IsInstances { object Is extends IsInstances with IsSupport { /** - * In truth, "all values of `A Is B` are `refl`". `reflAny` is that - * single value. + * In truth, "all values of `A Is B` are `refl`". `reflAny` is that single value. */ private[this] val reflAny = new Is[Any, Any] { def substitute[F[_]](fa: F[Any]) = fa } /** - * In normal circumstances the only `Is` value which is available is the - * computational identity `A Is A` at all types `A`. These "self loops" - * generate all of the behavior of equality and also ensure that at its - * heart `A Is B` is always just an identity relation. + * In normal circumstances the only `Is` value which is available is the computational identity `A Is A` at all types + * `A`. These "self loops" generate all of the behavior of equality and also ensure that at its heart `A Is B` is + * always just an identity relation. * - * Implementation note: all values of `refl` return the same (private) - * instance at whatever type is appropriate to save on allocations. + * Implementation note: all values of `refl` return the same (private) instance at whatever type is appropriate to + * save on allocations. */ @inline implicit def refl[A]: A Is A = reflAny.asInstanceOf[A Is A] /** - * It can be convenient to convert a `Predef.=:=` value into an `Is` value. - * This is not actually unsafe, but was previously labeled as such out - * of an abundance of caution + * It can be convenient to convert a `Predef.=:=` value into an `Is` value. This is not actually unsafe, but was + * previously labeled as such out of an abundance of caution */ @deprecated("use Is.isFromPredef", "2.2.0") @inline def unsafeFromPredef[A, B](eq: A =:= B): A Is B = diff --git a/core/src/main/scala/cats/evidence/package.scala b/core/src/main/scala/cats/evidence/package.scala index 292b7af115..8fbcdf3101 100644 --- a/core/src/main/scala/cats/evidence/package.scala +++ b/core/src/main/scala/cats/evidence/package.scala @@ -24,22 +24,18 @@ package cats package object evidence { /** - * A convenient type alias for Is, which declares that A is the same - * type as B. + * A convenient type alias for Is, which declares that A is the same type as B. */ type ===[A, B] = A Is B /** - * This type level equality represented by `Is` is referred to as - * "Leibniz equality", and it had the name "Leibniz" in the scalaz - * https://en.wikipedia.org/wiki/Gottfried_Wilhelm_Leibniz + * This type level equality represented by `Is` is referred to as "Leibniz equality", and it had the name "Leibniz" in + * the scalaz https://en.wikipedia.org/wiki/Gottfried_Wilhelm_Leibniz */ type Leibniz[A, B] = A Is B /** - * A convenient type alias for As, this declares that A is a - * subtype of B, and should be able to be a B is - * expected. + * A convenient type alias for As, this declares that A is a subtype of B, and should be able to be a B is expected. */ type <~<[-A, +B] = A As B @@ -49,10 +45,8 @@ package object evidence { type >~>[+B, -A] = A As B /** - * The property that a value of type A can be used in a context - * expecting a B if A <~< B is referred to as the "Liskov - * Substitution Principle", which is named for Barbara Liskov: - * https://en.wikipedia.org/wiki/Barbara_Liskov + * The property that a value of type A can be used in a context expecting a B if A <~< B is referred to as the "Liskov + * Substitution Principle", which is named for Barbara Liskov: https://en.wikipedia.org/wiki/Barbara_Liskov */ type Liskov[-A, +B] = A As B } diff --git a/core/src/main/scala/cats/instances/eq.scala b/core/src/main/scala/cats/instances/eq.scala index 5c96a8c219..40c915905f 100644 --- a/core/src/main/scala/cats/instances/eq.scala +++ b/core/src/main/scala/cats/instances/eq.scala @@ -29,15 +29,15 @@ trait EqInstances extends kernel.instances.EqInstances { new ContravariantMonoidal[Eq] { /** - * Defaults to the trivial equivalence relation - * contracting the type to a point + * Defaults to the trivial equivalence relation contracting the type to a point */ def unit: Eq[Unit] = Eq.allEqual /** * Derive an `Eq` for `B` given an `Eq[A]` and a function `B => A`. * - * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one mapping) + * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one + * mapping) */ def contramap[A, B](fa: Eq[A])(f: B => A): Eq[B] = Eq.by(f)(fa) diff --git a/core/src/main/scala/cats/instances/equiv.scala b/core/src/main/scala/cats/instances/equiv.scala index 941fd6e911..0f66721e17 100644 --- a/core/src/main/scala/cats/instances/equiv.scala +++ b/core/src/main/scala/cats/instances/equiv.scala @@ -29,8 +29,7 @@ trait EquivInstances { new ContravariantMonoidal[Equiv] { /** - * Defaults to trivially contracting the type - * to a point + * Defaults to trivially contracting the type to a point */ def unit: Equiv[Unit] = new Equiv[Unit] { @@ -40,7 +39,8 @@ trait EquivInstances { /** * Derive an `Equiv` for `B` given an `Equiv[A]` and a function `B => A`. * - * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one mapping) + * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one + * mapping) */ def contramap[A, B](fa: Equiv[A])(f: B => A): Equiv[B] = new Equiv[B] { diff --git a/core/src/main/scala/cats/instances/future.scala b/core/src/main/scala/cats/instances/future.scala index 30ae6c6a80..b0ac57d1f6 100644 --- a/core/src/main/scala/cats/instances/future.scala +++ b/core/src/main/scala/cats/instances/future.scala @@ -27,12 +27,13 @@ import scala.util.{Failure, Success} /** * @deprecated - * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone - * (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). - * We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]]. - * However, at this time there are no plans to remove these instances from Cats. + * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone (particularly the semantics of + * [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). We recommend using + * [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of + * [[scala.concurrent.Future Future]]. However, at this time there are no plans to remove these instances from Cats. * - * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] + * @see + * [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] */ trait FutureInstances extends FutureInstances1 { diff --git a/core/src/main/scala/cats/instances/order.scala b/core/src/main/scala/cats/instances/order.scala index 88f2e08956..11f6bef6a7 100644 --- a/core/src/main/scala/cats/instances/order.scala +++ b/core/src/main/scala/cats/instances/order.scala @@ -39,7 +39,8 @@ trait OrderInstances extends kernel.instances.OrderInstances { /** * Derive an `Order` for `B` given an `Order[A]` and a function `B => A`. * - * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one mapping) + * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one + * mapping) */ def contramap[A, B](fa: Order[A])(f: B => A): Order[B] = Order.by(f)(fa) diff --git a/core/src/main/scala/cats/instances/ordering.scala b/core/src/main/scala/cats/instances/ordering.scala index 08b5697f07..6caff93a6f 100644 --- a/core/src/main/scala/cats/instances/ordering.scala +++ b/core/src/main/scala/cats/instances/ordering.scala @@ -31,7 +31,8 @@ trait OrderingInstances { new ContravariantMonoidal[Ordering] { /** - * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one mapping) + * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one + * mapping) */ def unit: Ordering[Unit] = Order[Unit].toOrdering diff --git a/core/src/main/scala/cats/instances/partialOrder.scala b/core/src/main/scala/cats/instances/partialOrder.scala index dee8ae942c..78c4461e51 100644 --- a/core/src/main/scala/cats/instances/partialOrder.scala +++ b/core/src/main/scala/cats/instances/partialOrder.scala @@ -32,7 +32,8 @@ trait PartialOrderInstances extends kernel.instances.PartialOrderInstances { /** * Derive a `PartialOrder` for `B` given a `PartialOrder[A]` and a function `B => A`. * - * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one mapping) + * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one + * mapping) */ def contramap[A, B](fa: PartialOrder[A])(f: B => A): PartialOrder[B] = PartialOrder.by[B, A](f)(fa) diff --git a/core/src/main/scala/cats/instances/partialOrdering.scala b/core/src/main/scala/cats/instances/partialOrdering.scala index 586c9492dd..99721b9f1c 100644 --- a/core/src/main/scala/cats/instances/partialOrdering.scala +++ b/core/src/main/scala/cats/instances/partialOrdering.scala @@ -31,7 +31,8 @@ trait PartialOrderingInstances { /** * Derive a `PartialOrdering` for `B` given a `PartialOrdering[A]` and a function `B => A`. * - * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one mapping) + * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one + * mapping) */ def contramap[A, B](fa: PartialOrdering[A])(f: B => A): PartialOrdering[B] = new PartialOrdering[B] { diff --git a/core/src/main/scala/cats/instances/try.scala b/core/src/main/scala/cats/instances/try.scala index 91b85192a4..7a27026c53 100644 --- a/core/src/main/scala/cats/instances/try.scala +++ b/core/src/main/scala/cats/instances/try.scala @@ -222,9 +222,8 @@ trait TryInstances extends TryInstances1 { } /** - * you may wish to do equality by making `implicit val eqT: Eq[Throwable] = Eq.allEqual` - * doing a fine grained equality on Throwable can make the code very execution - * order dependent + * you may wish to do equality by making `implicit val eqT: Eq[Throwable] = Eq.allEqual` doing a fine grained equality + * on Throwable can make the code very execution order dependent */ implicit def catsStdEqForTry[A](implicit A: Eq[A], T: Eq[Throwable]): Eq[Try[A]] = Eq.catsStdEqForTry @@ -233,8 +232,8 @@ trait TryInstances extends TryInstances1 { private[instances] object TryInstances { /** - * A `Failure` can be statically typed as `Try[A]` for all `A`, because it - * does not actually contain an `A` value (as `Success[A]` does). + * A `Failure` can be statically typed as `Try[A]` for all `A`, because it does not actually contain an `A` value (as + * `Success[A]` does). */ @inline final def castFailure[A](f: Failure[?]): Try[A] = f.asInstanceOf[Try[A]] } diff --git a/core/src/main/scala/cats/package.scala b/core/src/main/scala/cats/package.scala index a9579bd56a..86c524070a 100644 --- a/core/src/main/scala/cats/package.scala +++ b/core/src/main/scala/cats/package.scala @@ -25,35 +25,34 @@ import cats.data.Ior /** * The `cats` root package contains all the trait signatures of most Scala type classes. * - * Cats type classes are implemented using the approach from the - * "[[https://i.cs.hku.hk/~bruno/papers/TypeClasses.pdf Type classes as objects and implicits]]" article. + * Cats type classes are implemented using the approach from the "[[https://i.cs.hku.hk/~bruno/papers/TypeClasses.pdf + * Type classes as objects and implicits]]" article. * * For each type class, `cats` provides four pieces: - * - Its '''signature''': a trait that is polymorphic on a type parameter. - * Type class traits inherit from other type classes to indicate that any implementation of the lower type class - * (e.g. [[Applicative `Applicative`]]) - * can also serve as an instance for the higher type class (e.g. [[Functor `Functor`]]). - * - Type class '''instances''', which are classes and objects that implement one or more type class signatures for some specific types. - * Type class instances for several data types from the Java or Scala standard libraries are declared - * in the subpackage [[cats.instances `cats.instances`]]. - * - '''Syntax extensions''', each of which provides the methods of the type class defined as extension methods - * (which in Scala 2 are encoded as implicit classes) for values of any type `F`; given that an instance of the type class - * for the receiver type (`this`) is in the implicit scope. - * Syntax extensions are declared in the [[cats.syntax `cats.syntax`]] package. - * - A set of '''laws''', that are also generic on the type of the class, and are only defined on the operations of the type class. - * The purpose of these laws is to declare some algebraic relations (equations) between Scala expressions involving the operations - * of the type class, and test (but not verify) that implemented instances satisfy those equations. - * Laws are defined in the [[cats.laws `cats.laws`]] package. + * - Its '''signature''': a trait that is polymorphic on a type parameter. Type class traits inherit from other type + * classes to indicate that any implementation of the lower type class (e.g. [[Applicative `Applicative`]]) can also + * serve as an instance for the higher type class (e.g. [[Functor `Functor`]]). + * - Type class '''instances''', which are classes and objects that implement one or more type class signatures for + * some specific types. Type class instances for several data types from the Java or Scala standard libraries are + * declared in the subpackage [[cats.instances `cats.instances`]]. + * - '''Syntax extensions''', each of which provides the methods of the type class defined as extension methods (which + * in Scala 2 are encoded as implicit classes) for values of any type `F`; given that an instance of the type class + * for the receiver type (`this`) is in the implicit scope. Syntax extensions are declared in the + * [[cats.syntax `cats.syntax`]] package. + * - A set of '''laws''', that are also generic on the type of the class, and are only defined on the operations of + * the type class. The purpose of these laws is to declare some algebraic relations (equations) between Scala + * expressions involving the operations of the type class, and test (but not verify) that implemented instances + * satisfy those equations. Laws are defined in the [[cats.laws `cats.laws`]] package. * * Although most of cats type classes are declared in this package, some are declared in other packages: - * - type classes that operate on base types (kind `*`), and their implementations for standard library types, - * are contained in [[cats.kernel `cats.kernel`]], which is a different SBT project. However, they are re-exported from this package. - * - type classes of kind `F[_, _]`, - * such as [[cats.arrow.Profunctor `cats.arrow.Profunctor`]] or [[cats.arrow.Arrow `cats.arrow.Arrow`]], - * which are relevant for - * Functional Reactive Programming or optics, are declared in the [[cats.arrow `cats.arrow`]] package. - * - Also, those type classes that abstract over (pure or impure) functional runtime effects are declared - * in the [[https://typelevel.org/cats-effect/ cats-effect library]]. + * - type classes that operate on base types (kind `*`), and their implementations for standard library types, are + * contained in [[cats.kernel `cats.kernel`]], which is a different SBT project. However, they are re-exported from + * this package. + * - type classes of kind `F[_, _]`, such as [[cats.arrow.Profunctor `cats.arrow.Profunctor`]] or + * [[cats.arrow.Arrow `cats.arrow.Arrow`]], which are relevant for Functional Reactive Programming or optics, are + * declared in the [[cats.arrow `cats.arrow`]] package. + * - Also, those type classes that abstract over (pure or impure) functional runtime effects are declared in the + * [[https://typelevel.org/cats-effect/ cats-effect library]]. * - Some type classes for which no laws can be provided are left out of the main road, in a small and dirty alley. * These are the [[alleycats `alleycats`]]. */ @@ -75,19 +74,15 @@ package object cats { type :≺:[F[_], G[_]] = InjectK[F, G] /** - * Identity, encoded as `type Id[A] = A`, a convenient alias to make - * identity instances well-kinded. + * Identity, encoded as `type Id[A] = A`, a convenient alias to make identity instances well-kinded. * - * The identity monad can be seen as the ambient monad that encodes - * the effect of having no effect. It is ambient in the sense that - * plain pure values are values of `Id`. + * The identity monad can be seen as the ambient monad that encodes the effect of having no effect. It is ambient in + * the sense that plain pure values are values of `Id`. * - * For instance, the [[cats.Functor]] instance for `[[cats.Id]]` - * allows us to apply a function `A => B` to an `Id[A]` and get an - * `Id[B]`. However, an `Id[A]` is the same as `A`, so all we're doing - * is applying a pure function of type `A => B` to a pure value of - * type `A` to get a pure value of type `B`. That is, the instance - * encodes pure unary function application. + * For instance, the [[cats.Functor]] instance for `[[cats.Id]]` allows us to apply a function `A => B` to an `Id[A]` + * and get an `Id[B]`. However, an `Id[A]` is the same as `A`, so all we're doing is applying a pure function of type + * `A => B` to a pure value of type `A` to get a pure value of type `B`. That is, the instance encodes pure unary + * function application. */ type Id[A] = A object Id { diff --git a/core/src/main/scala/cats/syntax/applicativeError.scala b/core/src/main/scala/cats/syntax/applicativeError.scala index 352658fc8e..779cf21b09 100644 --- a/core/src/main/scala/cats/syntax/applicativeError.scala +++ b/core/src/main/scala/cats/syntax/applicativeError.scala @@ -103,8 +103,8 @@ final class ApplicativeErrorOps[F[_], E, A](private val fa: F[A]) extends AnyVal F.handleErrorWith(fa)(_ => other) /** - * Transform certain errors using `pf` and rethrow them. - * Non matching errors and successful values are not affected by this function. + * Transform certain errors using `pf` and rethrow them. Non matching errors and successful values are not affected by + * this function. * * Example: * {{{ @@ -122,8 +122,8 @@ final class ApplicativeErrorOps[F[_], E, A](private val fa: F[A]) extends AnyVal * res2: Either[String,Int] = Right(1) * }}} * - * This is the same as `MonadErrorOps#adaptError`. It cannot have the same name because - * this would result in ambiguous implicits. + * This is the same as `MonadErrorOps#adaptError`. It cannot have the same name because this would result in ambiguous + * implicits. */ def adaptErr(pf: PartialFunction[E, E])(implicit F: ApplicativeError[F, E]): F[A] = F.adaptError(fa)(pf) diff --git a/core/src/main/scala/cats/syntax/apply.scala b/core/src/main/scala/cats/syntax/apply.scala index dcb0d95a67..241fa91461 100644 --- a/core/src/main/scala/cats/syntax/apply.scala +++ b/core/src/main/scala/cats/syntax/apply.scala @@ -50,7 +50,8 @@ private[syntax] trait ApplySyntaxBinCompat0 { final class ApplyFABOps[F[_], A, B](private val fab: F[A => B]) extends AnyVal { /** - * @see [[Apply.ap]]. + * @see + * [[Apply.ap]]. * * Example: * {{{ @@ -85,7 +86,8 @@ final class ApplyFABOps[F[_], A, B](private val fab: F[A => B]) extends AnyVal { final class ApplyFABCOps[F[_], A, B, C](private val ff: F[(A, B) => C]) extends AnyVal { /** - * @see [[Apply.ap2]]. + * @see + * [[Apply.ap2]]. * * Example: * {{{ @@ -109,7 +111,6 @@ final class ApplyFABCOps[F[_], A, B, C](private val ff: F[(A, B) => C]) extends * scala> noneF.ap2(noneInt, noneInt) * res3: Option[Long] = None * }}} - * */ def ap2(fa: F[A], fb: F[B])(implicit F: Apply[F]): F[C] = F.ap2(ff)(fa, fb) } @@ -137,7 +138,8 @@ final class ApplyOps[F[_], A](private val fa: F[A]) extends AnyVal { F.productL(fa)(fb) /** - * @see [[Apply.productR]]. + * @see + * [[Apply.productR]]. * * Example: * {{{ @@ -168,7 +170,8 @@ final class ApplyOps[F[_], A](private val fa: F[A]) extends AnyVal { def productR[B](fb: F[B])(implicit F: Apply[F]): F[B] = F.productR(fa)(fb) /** - * @see [[Apply.productL]]. + * @see + * [[Apply.productL]]. * * Example: * {{{ @@ -209,7 +212,8 @@ final class ApplyOps[F[_], A](private val fa: F[A]) extends AnyVal { def <*[B](fb: F[B])(implicit F: Apply[F]): F[A] = F.<*(fa)(fb) /** - * @see [[Apply.map2]]. + * @see + * [[Apply.map2]]. * * Example: * {{{ @@ -237,7 +241,8 @@ final class ApplyOps[F[_], A](private val fa: F[A]) extends AnyVal { F.map2(fa, fb)(f) /** - * @see [[Apply.map2Eval]]. + * @see + * [[Apply.map2Eval]]. * * Example: * {{{ diff --git a/core/src/main/scala/cats/syntax/bitraverse.scala b/core/src/main/scala/cats/syntax/bitraverse.scala index 9980880fa6..9ec582dc29 100644 --- a/core/src/main/scala/cats/syntax/bitraverse.scala +++ b/core/src/main/scala/cats/syntax/bitraverse.scala @@ -58,11 +58,11 @@ private[syntax] trait BitraverseSyntaxBinCompat0 { final private[syntax] class BitraverseOpsBinCompat0[F[_, _], A, B](val fab: F[A, B]) extends AnyVal { /** - * Traverse over the left side of the structure. - * For the right side, use the standard `traverse` from [[cats.Traverse]]. + * Traverse over the left side of the structure. For the right side, use the standard `traverse` from + * [[cats.Traverse]]. * - * Example: - * {{{ + * Example: + * {{{ * scala> import cats.syntax.all._ * * scala> val intAndString: (Int, String) = (7, "test") @@ -72,7 +72,7 @@ final private[syntax] class BitraverseOpsBinCompat0[F[_, _], A, B](val fab: F[A, * * scala> intAndString.leftTraverse(i => Option(i).filter(_ < 5)) * res2: Option[(Int, String)] = None - * }}} + * }}} */ def leftTraverse[G[_], C](f: A => G[C])(implicit F: Bitraverse[F], G: Applicative[G]): G[F[C, B]] = F.leftTraverse[G, A, B, C](fab)(f) @@ -81,8 +81,7 @@ final private[syntax] class BitraverseOpsBinCompat0[F[_, _], A, B](val fab: F[A, final class LeftNestedBitraverseOps[F[_, _], G[_], A, B](val fgab: F[G[A], B]) extends AnyVal { /** - * Sequence the left side of the structure. - * For the right side, use the standard `sequence` from [[cats.Traverse]]. + * Sequence the left side of the structure. For the right side, use the standard `sequence` from [[cats.Traverse]]. * * Example: * {{{ diff --git a/core/src/main/scala/cats/syntax/either.scala b/core/src/main/scala/cats/syntax/either.scala index ab75c85799..a8bb0b89b5 100644 --- a/core/src/main/scala/cats/syntax/either.scala +++ b/core/src/main/scala/cats/syntax/either.scala @@ -44,7 +44,9 @@ trait EitherSyntax { object EitherSyntax { /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[syntax] class CatchOnlyPartiallyApplied[T](private val dummy: Boolean = true) extends AnyVal { def apply[A](f: => A)(implicit CT: ClassTag[T], NT: NotNull[T]): Either[T, A] = @@ -151,8 +153,8 @@ final class EitherOps[A, B](private val eab: Either[A, B]) extends AnyVal { } /** - * Returns a [[cats.data.ValidatedNel]] representation of this disjunction with the `Left` value - * as a single element on the `Invalid` side of the [[cats.data.NonEmptyList]]. + * Returns a [[cats.data.ValidatedNel]] representation of this disjunction with the `Left` value as a single element + * on the `Invalid` side of the [[cats.data.NonEmptyList]]. */ def toValidatedNel[AA >: A]: ValidatedNel[AA, B] = eab match { @@ -284,13 +286,10 @@ final class EitherOps[A, B](private val eab: Either[A, B]) extends AnyVal { /** * Combine with another `Either` value. * - * If this `Either` is a `Left` then it will be returned as-is. - * If this `Either` is a `Right` and `that` `Either` is a left, then `that` will be - * returned. - * If both `Either`s are `Right`s, then the `Semigroup[BB]` instance will be used - * to combine both values and return them as a `Right`. - * Note: If both `Either`s are `Left`s then their values are not combined. Use - * `Validated` if you prefer to combine `Left` values. + * If this `Either` is a `Left` then it will be returned as-is. If this `Either` is a `Right` and `that` `Either` is a + * left, then `that` will be returned. If both `Either`s are `Right`s, then the `Semigroup[BB]` instance will be used + * to combine both values and return them as a `Right`. Note: If both `Either`s are `Left`s then their values are not + * combined. Use `Validated` if you prefer to combine `Left` values. * * Examples: * {{{ @@ -385,8 +384,8 @@ final class EitherObjectOps(private val either: Either.type) extends AnyVal { def rightNel[A, B](b: B): EitherNel[A, B] = Right(b) /** - * Evaluates the specified block, catching exceptions of the specified type and returning them on the left side of - * the resulting `Either`. Uncaught exceptions are propagated. + * Evaluates the specified block, catching exceptions of the specified type and returning them on the left side of the + * resulting `Either`. Uncaught exceptions are propagated. * * For example: * {{{ @@ -415,8 +414,8 @@ final class EitherObjectOps(private val either: Either.type) extends AnyVal { } /** - * Converts an `Option[B]` to an `Either[A, B]`, where the provided `ifNone` values is returned on - * the left of the `Either` when the specified `Option` is `None`. + * Converts an `Option[B]` to an `Either[A, B]`, where the provided `ifNone` values is returned on the left of the + * `Either` when the specified `Option` is `None`. */ def fromOption[A, B](o: Option[B], ifNone: => A): Either[A, B] = o match { @@ -432,7 +431,9 @@ final class EitherObjectOps(private val either: Either.type) extends AnyVal { /** * Returns `Left(ifTrue)` when the `cond` is true, otherwise `Right(())` * - * @example {{{ + * @example + * + * {{{ * val tooMany = 5 * val x: Int = ??? * Either.raiseWhen(x >= tooMany)(new IllegalArgumentException("Too many")) @@ -444,7 +445,9 @@ final class EitherObjectOps(private val either: Either.type) extends AnyVal { /** * Returns `Left(ifFalse)` when `cond` is false, otherwise `Right(())` * - * @example {{{ + * @example + * + * {{{ * val tooMany = 5 * val x: Int = ??? * Either.raiseUnless(x < tooMany)(new IllegalArgumentException("Too many")) @@ -546,8 +549,8 @@ final private[syntax] class EitherIdOpsBinCompat0[A](private val value: A) exten final private[syntax] class EitherOpsBinCompat0[A, B](private val value: Either[A, B]) extends AnyVal { /** - * Returns a [[cats.data.ValidatedNec]] representation of this disjunction with the `Left` value - * as a single element on the `Invalid` side of the [[cats.data.NonEmptyList]]. + * Returns a [[cats.data.ValidatedNec]] representation of this disjunction with the `Left` value as a single element + * on the `Invalid` side of the [[cats.data.NonEmptyList]]. */ def toValidatedNec: ValidatedNec[A, B] = value match { diff --git a/core/src/main/scala/cats/syntax/eitherK.scala b/core/src/main/scala/cats/syntax/eitherK.scala index 0cabf0dce3..4746984f39 100644 --- a/core/src/main/scala/cats/syntax/eitherK.scala +++ b/core/src/main/scala/cats/syntax/eitherK.scala @@ -33,7 +33,8 @@ final class EitherKOps[F[_], A](private val fa: F[A]) extends AnyVal { /** * Lift an `F[A]` into a `EitherK[F, G, A]` for any type constructor `G[_]`. * - * @see [[rightc]] to swap the order of `F` and `G` in the result type. + * @see + * [[rightc]] to swap the order of `F` and `G` in the result type. * * Example: * {{{ @@ -49,7 +50,8 @@ final class EitherKOps[F[_], A](private val fa: F[A]) extends AnyVal { /** * Lift an `F[A]` into a `EitherK[G, F, A]` for any type constructor `G[_]`. * - * @see [[leftc]] to swap the order of `F` and `G` in the result type. + * @see + * [[leftc]] to swap the order of `F` and `G` in the result type. * * Example: * {{{ diff --git a/core/src/main/scala/cats/syntax/flatMap.scala b/core/src/main/scala/cats/syntax/flatMap.scala index 9791f47450..179b27c9bb 100644 --- a/core/src/main/scala/cats/syntax/flatMap.scala +++ b/core/src/main/scala/cats/syntax/flatMap.scala @@ -47,9 +47,8 @@ final class FlatMapOps[F[_], A](private val fa: F[A]) extends AnyVal { /** * Alias for `fa.flatMap(_ => fb)`. * - * Unlike `*>`, `fb` is defined as a by-name parameter, allowing this - * method to be used in cases where computing `fb` is not stack safe - * unless suspended in a `flatMap`. + * Unlike `*>`, `fb` is defined as a by-name parameter, allowing this method to be used in cases where computing `fb` + * is not stack safe unless suspended in a `flatMap`. */ def >>[B](fb: => F[B])(implicit F: FlatMap[F]): F[B] = F.flatMap(fa)(_ => fb) @@ -64,16 +63,14 @@ final class FlatMapOps[F[_], A](private val fa: F[A]) extends AnyVal { F.productLEval(fa)(fb) /** - * Like an infinite loop of >> calls. This is most useful effect loops - * that you want to run forever in for instance a server. + * Like an infinite loop of >> calls. This is most useful effect loops that you want to run forever in for instance a + * server. * * This will be an infinite loop, or it will return an F[Nothing]. * - * Be careful using this. - * For instance, a List of length k will produce a list of length k^n at iteration - * n. This means if k = 0, we return an empty list, if k = 1, we loop forever - * allocating single element lists, but if we have a k > 1, we will allocate - * exponentially increasing memory and very quickly OOM. + * Be careful using this. For instance, a List of length k will produce a list of length k^n at iteration + * n. This means if k = 0, we return an empty list, if k = 1, we loop forever allocating single element lists, but + * if we have a k > 1, we will allocate exponentially increasing memory and very quickly OOM. */ def foreverM[B](implicit F: FlatMap[F]): F[B] = F.foreverM[A, B](fa) } @@ -135,9 +132,8 @@ final class FlatMapIdOps[A](private val a: A) extends AnyVal { def tailRecM[F[_], B](f: A => F[Either[A, B]])(implicit F: FlatMap[F]): F[B] = F.tailRecM(a)(f) /** - * iterateForeverM is almost exclusively useful for effect types. For instance, - * A may be some state, we may take the current state, run some effect to get - * a new state and repeat. + * iterateForeverM is almost exclusively useful for effect types. For instance, A may be some state, we may take the + * current state, run some effect to get a new state and repeat. */ def iterateForeverM[F[_], B](f: A => F[A])(implicit F: FlatMap[F]): F[B] = F.iterateForeverM[A, B](a)(f) } @@ -150,9 +146,8 @@ trait FlatMapOptionSyntax { final class FlatMapOptionOps[F[_], A](private val fopta: F[Option[A]]) extends AnyVal { /** - * This repeats an F until we get defined values. This can be useful - * for polling type operations on State (or RNG) Monads, or in effect - * monads. + * This repeats an F until we get defined values. This can be useful for polling type operations on State (or RNG) + * Monads, or in effect monads. */ def untilDefinedM(implicit F: FlatMap[F]): F[A] = F.untilDefinedM[A](fopta) } diff --git a/core/src/main/scala/cats/syntax/foldable.scala b/core/src/main/scala/cats/syntax/foldable.scala index b70eb71674..2558f94456 100644 --- a/core/src/main/scala/cats/syntax/foldable.scala +++ b/core/src/main/scala/cats/syntax/foldable.scala @@ -53,7 +53,8 @@ final class NestedFoldableOps[F[_], G[_], A](private val fga: F[G[A]]) extends A def sequence_(implicit F: Foldable[F], G: Applicative[G]): G[Unit] = sequenceVoid /** - * @see [[Foldable.foldK]]. + * @see + * [[Foldable.foldK]]. * * Example: * {{{ @@ -129,8 +130,8 @@ final class FoldableOps[F[_], A](private val fa: F[A]) extends AnyVal { /** * Monadic version of `collectFirstSome`. * - * If there are no elements, the result is `None`. `collectFirstSomeM` short-circuits, - * i.e. once a Some element is found, no further effects are produced. + * If there are no elements, the result is `None`. `collectFirstSomeM` short-circuits, i.e. once a Some element is + * found, no further effects are produced. * * For example: * {{{ @@ -160,8 +161,8 @@ final class FoldableOps[F[_], A](private val fa: F[A]) extends AnyVal { /** * Find the first element matching the effectful predicate, if one exists. * - * If there are no elements, the result is `None`. `findM` short-circuits, - * i.e. once an element is found, no further effects are produced. + * If there are no elements, the result is `None`. `findM` short-circuits, i.e. once an element is found, no further + * effects are produced. * * For example: * {{{ @@ -233,8 +234,8 @@ final class FoldableOps0[F[_], A](private val fa: F[A]) extends AnyVal { new FoldableOps(fa).mkString_("", delim, "") /** - * Fold implemented by mapping `A` values into `B` in a context `G` and then - * combining them using the `MonoidK[G]` instance. + * Fold implemented by mapping `A` values into `B` in a context `G` and then combining them using the `MonoidK[G]` + * instance. * * {{{ * scala> import cats._, cats.syntax.all._ @@ -284,8 +285,8 @@ final class FoldableOps0[F[_], A](private val fa: F[A]) extends AnyVal { F.partitionBifoldM[G, H, A, B, C](fa)(f)(A, M, H) /** - * Separate this Foldable into a Tuple by an effectful separating function `A => G[Either[B, C]]` - * Equivalent to `Traverse#traverse` over `Alternative#separate` + * Separate this Foldable into a Tuple by an effectful separating function `A => G[Either[B, C]]` Equivalent to + * `Traverse#traverse` over `Alternative#separate` * * {{{ * scala> import cats.syntax.all._, cats.Eval diff --git a/core/src/main/scala/cats/syntax/function1.scala b/core/src/main/scala/cats/syntax/function1.scala index 7b4b74c7a5..3432a349d1 100644 --- a/core/src/main/scala/cats/syntax/function1.scala +++ b/core/src/main/scala/cats/syntax/function1.scala @@ -33,8 +33,7 @@ trait Function1Syntax { final class Function1Ops[F[_]: Functor, A, B](fab: F[Function1[A, B]]) { /** - * Given a function in the Functor context and a plain value, supplies the - * value to the function. + * Given a function in the Functor context and a plain value, supplies the value to the function. * * Example: * {{{ diff --git a/core/src/main/scala/cats/syntax/list.scala b/core/src/main/scala/cats/syntax/list.scala index bbbc635795..c3b23597c3 100644 --- a/core/src/main/scala/cats/syntax/list.scala +++ b/core/src/main/scala/cats/syntax/list.scala @@ -51,8 +51,7 @@ final class ListOps[A](private val la: List[A]) extends AnyVal { def toNel: Option[NonEmptyList[A]] = NonEmptyList.fromList(la) /** - * Groups elements inside this `List` according to the `Order` of the keys - * produced by the given mapping function. + * Groups elements inside this `List` according to the `Order` of the keys produced by the given mapping function. * * {{{ * scala> import cats.data.NonEmptyList @@ -73,8 +72,8 @@ final class ListOps[A](private val la: List[A]) extends AnyVal { } /** - * Groups elements inside this `List` according to the `Order` of the keys - * produced by the given mapping monadic function. + * Groups elements inside this `List` according to the `Order` of the keys produced by the given mapping monadic + * function. * * {{{ * scala> import cats.data.NonEmptyList @@ -99,8 +98,7 @@ final class ListOps[A](private val la: List[A]) extends AnyVal { } /** - * Produces a `NonEmptyList` containing cumulative results of applying the - * operator going left to right. + * Produces a `NonEmptyList` containing cumulative results of applying the operator going left to right. * * Example: * {{{ @@ -120,8 +118,7 @@ final class ListOps[A](private val la: List[A]) extends AnyVal { NonEmptyList.fromListUnsafe(la.scanLeft(b)(f)) /** - * Produces a `NonEmptyList` containing cumulative results of applying the - * operator going right to left. + * Produces a `NonEmptyList` containing cumulative results of applying the operator going right to left. * * Example: * {{{ @@ -148,8 +145,7 @@ private[syntax] trait ListSyntaxBinCompat0 { final private[syntax] class ListOpsBinCompat0[A](private val la: List[A]) extends AnyVal { /** - * Groups elements inside this `List` according to the `Order` of the keys - * produced by the given mapping function. + * Groups elements inside this `List` according to the `Order` of the keys produced by the given mapping function. * * {{{ * scala> import cats.data.NonEmptyChain diff --git a/core/src/main/scala/cats/syntax/monadError.scala b/core/src/main/scala/cats/syntax/monadError.scala index 5b13b52059..deb9202f9e 100644 --- a/core/src/main/scala/cats/syntax/monadError.scala +++ b/core/src/main/scala/cats/syntax/monadError.scala @@ -40,8 +40,8 @@ final class MonadErrorOps[F[_], E, A](private val fa: F[A]) extends AnyVal { F.ensureOr(fa)(error)(predicate) /** - * Turns a successful value into the error returned by a given partial function if it is - * in the partial function's domain. + * Turns a successful value into the error returned by a given partial function if it is in the partial function's + * domain. */ def reject(pf: PartialFunction[A, E])(implicit F: MonadError[F, E]): F[A] = F.flatMap(fa) { a => diff --git a/core/src/main/scala/cats/syntax/nonEmptyAlternative.scala b/core/src/main/scala/cats/syntax/nonEmptyAlternative.scala index ad5f830992..86c2e63518 100644 --- a/core/src/main/scala/cats/syntax/nonEmptyAlternative.scala +++ b/core/src/main/scala/cats/syntax/nonEmptyAlternative.scala @@ -30,7 +30,8 @@ trait NonEmptyAlternativeSyntax { final class NonEmptyAlternativeOps[F[_], A] private[syntax] (private val fa: F[A]) extends AnyVal { /** - * @see [[NonEmptyAlternative.prependK]] + * @see + * [[NonEmptyAlternative.prependK]] * * Example: * {{{ @@ -43,7 +44,8 @@ final class NonEmptyAlternativeOps[F[_], A] private[syntax] (private val fa: F[A def prependK(a: A)(implicit F: NonEmptyAlternative[F]): F[A] = F.prependK(a, fa) /** - * @see [[NonEmptyAlternative.appendK]] + * @see + * [[NonEmptyAlternative.appendK]] * * Example: * {{{ diff --git a/core/src/main/scala/cats/syntax/option.scala b/core/src/main/scala/cats/syntax/option.scala index 16cc8a3270..efb21e9cc3 100644 --- a/core/src/main/scala/cats/syntax/option.scala +++ b/core/src/main/scala/cats/syntax/option.scala @@ -46,8 +46,8 @@ final class OptionIdOps[A](private val a: A) extends AnyVal { /** * Wrap a value in `Some`. * - * `3.some` is equivalent to `Some(3)`, but the former will have an inferred - * return type of `Option[Int]` while the latter will have `Some[Int]`. + * `3.some` is equivalent to `Some(3)`, but the former will have an inferred return type of `Option[Int]` while the + * latter will have `Some[Int]`. * * Example: * {{{ @@ -62,9 +62,8 @@ final class OptionIdOps[A](private val a: A) extends AnyVal { final class OptionOps[A](private val oa: Option[A]) extends AnyVal { /** - * If the `Option` is a `Some`, return its value in a [[cats.data.Validated.Invalid]]. - * If the `Option` is `None`, return the provided `B` value in a - * [[cats.data.Validated.Valid]]. + * If the `Option` is a `Some`, return its value in a [[cats.data.Validated.Invalid]]. If the `Option` is `None`, + * return the provided `B` value in a [[cats.data.Validated.Valid]]. * * Example: * {{{ @@ -83,9 +82,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { def toInvalid[B](b: => B): Validated[A, B] = oa.fold[Validated[A, B]](Validated.Valid(b))(Validated.Invalid(_)) /** - * If the `Option` is a `Some`, wrap its value in a [[cats.data.NonEmptyList]] - * and return it in a [[cats.data.Validated.Invalid]]. - * If the `Option` is `None`, return the provided `B` value in a + * If the `Option` is a `Some`, wrap its value in a [[cats.data.NonEmptyList]] and return it in a + * [[cats.data.Validated.Invalid]]. If the `Option` is `None`, return the provided `B` value in a * [[cats.data.Validated.Valid]]. * * Example: @@ -106,9 +104,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { oa.fold[ValidatedNel[A, B]](Validated.Valid(b))(Validated.invalidNel) /** - * If the `Option` is a `Some`, wrap its value in a [[cats.data.Chain]] - * and return it in a [[cats.data.Validated.Invalid]]. - * If the `Option` is `None`, return the provided `B` value in a + * If the `Option` is a `Some`, wrap its value in a [[cats.data.Chain]] and return it in a + * [[cats.data.Validated.Invalid]]. If the `Option` is `None`, return the provided `B` value in a * [[cats.data.Validated.Valid]]. * * Example: @@ -129,9 +126,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { oa.fold[ValidatedNec[A, B]](Validated.Valid(b))(Validated.invalidNec) /** - * If the `Option` is a `Some`, return its value in a [[cats.data.Validated.Valid]]. - * If the `Option` is `None`, return the provided `B` value in a - * [[cats.data.Validated.Invalid]]. + * If the `Option` is a `Some`, return its value in a [[cats.data.Validated.Valid]]. If the `Option` is `None`, return + * the provided `B` value in a [[cats.data.Validated.Invalid]]. * * Example: * {{{ @@ -150,9 +146,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { def toValid[B](b: => B): Validated[B, A] = oa.fold[Validated[B, A]](Validated.Invalid(b))(Validated.Valid(_)) /** - * If the `Option` is a `Some`, return its value in a [[cats.data.Validated.Valid]]. - * If the `Option` is `None`, wrap the provided `B` value in a [[cats.data.NonEmptyList]] - * and return the result in a [[cats.data.Validated.Invalid]]. + * If the `Option` is a `Some`, return its value in a [[cats.data.Validated.Valid]]. If the `Option` is `None`, wrap + * the provided `B` value in a [[cats.data.NonEmptyList]] and return the result in a [[cats.data.Validated.Invalid]]. * * Example: * {{{ @@ -172,9 +167,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { oa.fold[ValidatedNel[B, A]](Validated.invalidNel(b))(Validated.Valid(_)) /** - * If the `Option` is a `Some`, return its value in a [[cats.data.Validated.Valid]]. - * If the `Option` is `None`, wrap the provided `B` value in a [[cats.data.Chain]] - * and return the result in a [[cats.data.Validated.Invalid]]. + * If the `Option` is a `Some`, return its value in a [[cats.data.Validated.Valid]]. If the `Option` is `None`, wrap + * the provided `B` value in a [[cats.data.Chain]] and return the result in a [[cats.data.Validated.Invalid]]. * * Example: * {{{ @@ -194,8 +188,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { oa.fold[ValidatedNec[B, A]](Validated.invalidNec(b))(Validated.Valid(_)) /** - * If the `Option` is a `Some`, return its value in a [[cats.data.Ior.Right]]. - * If the `Option` is `None`, wrap the provided `B` value in a [[cats.data.Ior.Left]] + * If the `Option` is a `Some`, return its value in a [[cats.data.Ior.Right]]. If the `Option` is `None`, wrap the + * provided `B` value in a [[cats.data.Ior.Left]] * * Example: * {{{ @@ -214,8 +208,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { def toRightIor[B](b: => B): Ior[B, A] = oa.fold[Ior[B, A]](Ior.Left(b))(Ior.Right(_)) /** - * If the `Option` is a `Some`, return its value in a [[cats.data.Ior.Left]]. - * If the `Option` is `None`, wrap the provided `B` value in a [[cats.data.Ior.Right]] + * If the `Option` is a `Some`, return its value in a [[cats.data.Ior.Left]]. If the `Option` is `None`, wrap the + * provided `B` value in a [[cats.data.Ior.Right]] * * Example: * {{{ @@ -234,9 +228,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { def toLeftIor[B](b: => B): Ior[A, B] = oa.fold[Ior[A, B]](Ior.Right(b))(Ior.Left(_)) /** - * If the `Option` is a `Some`, return its value in a [[scala.Right]]. - * If the `Option` is `None`, wrap the provided `B` value in a [[cats.data.NonEmptyList]] - * and return the result in a [[scala.Left]]. + * If the `Option` is a `Some`, return its value in a [[scala.Right]]. If the `Option` is `None`, wrap the provided + * `B` value in a [[cats.data.NonEmptyList]] and return the result in a [[scala.Left]]. * * Example: * {{{ @@ -255,9 +248,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { def toRightNel[B](b: => B): EitherNel[B, A] = oa.toRight(NonEmptyList.one(b)) /** - * If the `Option` is a `Some`, return its value in a [[scala.Right]]. - * If the `Option` is `None`, wrap the provided `B` value in a [[cats.data.NonEmptyChain]] - * and return the result in a [[scala.Left]]. + * If the `Option` is a `Some`, return its value in a [[scala.Right]]. If the `Option` is `None`, wrap the provided + * `B` value in a [[cats.data.NonEmptyChain]] and return the result in a [[scala.Left]]. * * Example: * {{{ @@ -276,10 +268,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { def toRightNec[B](b: => B): EitherNec[B, A] = oa.toRight(NonEmptyChain.one(b)) /** - * If the `Option` is a `Some`, wrap its value in a [[cats.data.NonEmptyList]] - * and return it in a [[scala.Left]]. - * If the `Option` is `None`, return the provided `B` value in a - * [[scala.Right]]. + * If the `Option` is a `Some`, wrap its value in a [[cats.data.NonEmptyList]] and return it in a [[scala.Left]]. If + * the `Option` is `None`, return the provided `B` value in a [[scala.Right]]. * * Example: * {{{ @@ -299,10 +289,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { oa.fold[EitherNel[A, B]](Right(b))(a => Left(NonEmptyList.one(a))) /** - * If the `Option` is a `Some`, wrap its value in a [[cats.data.NonEmptyChain]] - * and return it in a [[scala.Left]]. - * If the `Option` is `None`, return the provided `B` value in a - * [[scala.Right]]. + * If the `Option` is a `Some`, wrap its value in a [[cats.data.NonEmptyChain]] and return it in a [[scala.Left]]. If + * the `Option` is `None`, return the provided `B` value in a [[scala.Right]]. * * Example: * {{{ @@ -322,8 +310,7 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { oa.fold[EitherNec[A, B]](Right(b))(a => Left(NonEmptyChain.one(a))) /** - * If the `Option` is a `Some`, return its value. If the `Option` is `None`, - * return the `empty` value for `Monoid[A]`. + * If the `Option` is a `Some`, return its value. If the `Option` is `None`, return the `empty` value for `Monoid[A]`. * * Example: * {{{ @@ -356,9 +343,8 @@ final class OptionOps[A](private val oa: Option[A]) extends AnyVal { def liftTo[F[_]]: LiftToPartiallyApplied[F, A] = new LiftToPartiallyApplied(oa) /** - * Raise to an F[Unit], as long as it has an ApplicativeError[F, A] instance - * If the option is empty, an empty unit effect is given. - * If the option contains an error, it is raised. + * Raise to an F[Unit], as long as it has an ApplicativeError[F, A] instance If the option is empty, an empty unit + * effect is given. If the option contains an error, it is raised. * * Example: * {{{ diff --git a/core/src/main/scala/cats/syntax/reducible.scala b/core/src/main/scala/cats/syntax/reducible.scala index 1e07ad776e..5c11abbee4 100644 --- a/core/src/main/scala/cats/syntax/reducible.scala +++ b/core/src/main/scala/cats/syntax/reducible.scala @@ -39,8 +39,7 @@ private[syntax] trait ReducibleSyntaxBinCompat0 { final class ReducibleOps0[F[_], A](private val fa: F[A]) extends AnyVal { /** - * Apply `f` to each element of `fa` and combine them using the - * given `SemigroupK[G]`. + * Apply `f` to each element of `fa` and combine them using the given `SemigroupK[G]`. * * {{{ * scala> import cats._, cats.data._, cats.implicits._ diff --git a/core/src/main/scala/cats/syntax/semigroupal.scala b/core/src/main/scala/cats/syntax/semigroupal.scala index e80bd78fd1..aca4e85684 100644 --- a/core/src/main/scala/cats/syntax/semigroupal.scala +++ b/core/src/main/scala/cats/syntax/semigroupal.scala @@ -40,7 +40,8 @@ trait SemigroupalSyntax { final class SemigroupalOps2[F[_], A](private val fa: F[A]) extends AnyVal { /** - * @see [[Semigroupal.product]] + * @see + * [[Semigroupal.product]] * * Example: * {{{ diff --git a/core/src/main/scala/cats/syntax/set.scala b/core/src/main/scala/cats/syntax/set.scala index fa7d58a31b..14bae89499 100644 --- a/core/src/main/scala/cats/syntax/set.scala +++ b/core/src/main/scala/cats/syntax/set.scala @@ -52,8 +52,8 @@ final class SetOps[A](private val se: SortedSet[A]) extends AnyVal { def toNes: Option[NonEmptySet[A]] = NonEmptySet.fromSet(se) /** - * Groups elements inside this `SortedSet` according to the `Order` of the keys - * produced by the given mapping function. + * Groups elements inside this `SortedSet` according to the `Order` of the keys produced by the given mapping + * function. * * {{{ * scala> import cats.data.NonEmptySet diff --git a/core/src/main/scala/cats/syntax/unorderedFoldable.scala b/core/src/main/scala/cats/syntax/unorderedFoldable.scala index 2a793c2552..bf3bb6f9ff 100644 --- a/core/src/main/scala/cats/syntax/unorderedFoldable.scala +++ b/core/src/main/scala/cats/syntax/unorderedFoldable.scala @@ -30,8 +30,8 @@ trait UnorderedFoldableSyntax extends UnorderedFoldable.ToUnorderedFoldableOps { final class UnorderedFoldableOps[F[_], A](private val fa: F[A]) extends AnyVal { /** - * Tests if this `F[A]` contains `v` using the `Eq` instance for `A`, - * named contains_ to avoid conflict with existing contains which uses universal equality. + * Tests if this `F[A]` contains `v` using the `Eq` instance for `A`, named `contains_` to avoid conflict with + * existing contains which uses universal equality. * * Example: * {{{ diff --git a/core/src/main/scala/cats/syntax/vector.scala b/core/src/main/scala/cats/syntax/vector.scala index d32967a80b..75433a17d0 100644 --- a/core/src/main/scala/cats/syntax/vector.scala +++ b/core/src/main/scala/cats/syntax/vector.scala @@ -52,8 +52,7 @@ final class VectorOps[A](private val va: Vector[A]) extends AnyVal { def toNev: Option[NonEmptyVector[A]] = NonEmptyVector.fromVector(va) /** - * Groups elements inside this `Vector` according to the `Order` of the keys - * produced by the given mapping function. + * Groups elements inside this `Vector` according to the `Order` of the keys produced by the given mapping function. * * {{{ * scala> import cats.data.NonEmptyVector @@ -74,8 +73,8 @@ final class VectorOps[A](private val va: Vector[A]) extends AnyVal { } /** - * Groups elements inside this `Vector` according to the `Order` of the keys - * produced by the given mapping monadic function. + * Groups elements inside this `Vector` according to the `Order` of the keys produced by the given mapping monadic + * function. * * {{{ * scala> import cats.data.NonEmptyVector @@ -105,8 +104,7 @@ final class VectorOps[A](private val va: Vector[A]) extends AnyVal { } /** - * Produces a `NonEmptyVector` containing cumulative results of applying the - * operator going left to right. + * Produces a `NonEmptyVector` containing cumulative results of applying the operator going left to right. * * Example: * {{{ @@ -126,8 +124,7 @@ final class VectorOps[A](private val va: Vector[A]) extends AnyVal { NonEmptyVector.fromVectorUnsafe(va.scanLeft(b)(f)) /** - * Produces a `NonEmptyVector` containing cumulative results of applying the - * operator going right to left. + * Produces a `NonEmptyVector` containing cumulative results of applying the operator going right to left. * * Example: * {{{ diff --git a/free/src/main/scala-2.13+/cats/free/FreeStructuralInstances.scala b/free/src/main/scala-2.13+/cats/free/FreeStructuralInstances.scala index 94893de44a..673c07d518 100644 --- a/free/src/main/scala-2.13+/cats/free/FreeStructuralInstances.scala +++ b/free/src/main/scala-2.13+/cats/free/FreeStructuralInstances.scala @@ -23,28 +23,26 @@ package cats package free /** - * Free may be viewed either as a sort of sequential program construction mechanism, wherein - * programs are assembled and then finally interpreted via foldMap, or it may be viewed as a - * recursive data structure shaped by the ''pattern'' of its suspension functor. In this view, - * it is helpful to think of Free as being the following recursive type alias: + * Free may be viewed either as a sort of sequential program construction mechanism, wherein programs are assembled and + * then finally interpreted via foldMap, or it may be viewed as a recursive data structure shaped by the ''pattern'' of + * its suspension functor. In this view, it is helpful to think of Free as being the following recursive type alias: * * {{{ * type Free[S[_], A] = Either[S[Free[S, A]], A] * }}} * - * Thus, a Free is a tree of Either(s) in which the data (of type A) is at the leaves, and each - * branching point is defined by the shape of the S functor. This kind of structural interpretation - * of Free is very useful in certain contexts, such as when representing expression trees in - * compilers and interpreters. + * Thus, a Free is a tree of Either(s) in which the data (of type A) is at the leaves, and each branching point is + * defined by the shape of the S functor. This kind of structural interpretation of Free is very useful in certain + * contexts, such as when representing expression trees in compilers and interpreters. * - * Using this interpretation, we can define many common instances over the ''data structure'' of - * Free, most notably Eq and Traverse (Show is also possible, though far less useful). This makes - * it much more convenient to use Free structures as if they were conventional data structures. + * Using this interpretation, we can define many common instances over the ''data structure'' of Free, most notably Eq + * and Traverse (Show is also possible, though far less useful). This makes it much more convenient to use Free + * structures as if they were conventional data structures. * - * Unfortunately, this functionality fundamentally requires recursive implicit resolution. This - * feature was added to Scala in 2.13 (and retained in Scala 3) in the form of by-name implicits, - * but is fundamentally unavailable in Scala 2.12 and earlier without using something like Shapeless. - * For that reason, all of these instances are only available on 2.13 and above. + * Unfortunately, this functionality fundamentally requires recursive implicit resolution. This feature was added to + * Scala in 2.13 (and retained in Scala 3) in the form of by-name implicits, but is fundamentally unavailable in Scala + * 2.12 and earlier without using something like Shapeless. For that reason, all of these instances are only available + * on 2.13 and above. */ private trait FreeStructuralInstances extends FreeStructuralInstances0 diff --git a/free/src/main/scala-2/cats/free/FreeFoldStep.scala b/free/src/main/scala-2/cats/free/FreeFoldStep.scala index dccf6b246f..b48cf8986f 100644 --- a/free/src/main/scala-2/cats/free/FreeFoldStep.scala +++ b/free/src/main/scala-2/cats/free/FreeFoldStep.scala @@ -29,8 +29,7 @@ private[free] trait FreeFoldStep[S[_], A] { def step: Free[S, A] /** - * A combination of step and fold. May be used to define interpreters with custom - * (non-monoidial) control flow. + * A combination of step and fold. May be used to define interpreters with custom (non-monoidial) control flow. */ final def foldStep[B]( onPure: A => B, diff --git a/free/src/main/scala-3/cats/free/FreeFoldStep.scala b/free/src/main/scala-3/cats/free/FreeFoldStep.scala index 5aa6e44c8d..7247324f4b 100644 --- a/free/src/main/scala-3/cats/free/FreeFoldStep.scala +++ b/free/src/main/scala-3/cats/free/FreeFoldStep.scala @@ -31,8 +31,7 @@ private[free] trait FreeFoldStep[S[_], A] { private type OnFlatMapped[X] = (S[X], X => Free[S, A]) /** - * A combination of step and fold. May be used to define interpreters with custom - * (non-monoidial) control flow. + * A combination of step and fold. May be used to define interpreters with custom (non-monoidial) control flow. */ final def foldStep[B]( onPure: A => B, diff --git a/free/src/main/scala/cats/free/Cofree.scala b/free/src/main/scala/cats/free/Cofree.scala index 5c7769d157..014190ab75 100644 --- a/free/src/main/scala/cats/free/Cofree.scala +++ b/free/src/main/scala/cats/free/Cofree.scala @@ -23,10 +23,10 @@ package cats package free /** - * A free comonad for some branching functor `S`. Branching is done lazily using [[Eval]]. - * A tree with data at the branches, as opposed to [[Free]] which is a tree with data at the leaves. - * Not an instruction set functor made into a program monad as in [[Free]], but an instruction set's outputs as a - * functor made into a tree of the possible worlds reachable using the instruction set. + * A free comonad for some branching functor `S`. Branching is done lazily using [[Eval]]. A tree with data at the + * branches, as opposed to [[Free]] which is a tree with data at the leaves. Not an instruction set functor made into a + * program monad as in [[Free]], but an instruction set's outputs as a functor made into a tree of the possible worlds + * reachable using the instruction set. * * This Scala implementation of `Cofree` and its usages are derived from * [[https://github.com/scalaz/scalaz/blob/series/7.3.x/core/src/main/scala/scalaz/Cofree.scala Scalaz's Cofree]], diff --git a/free/src/main/scala/cats/free/ContravariantCoyoneda.scala b/free/src/main/scala/cats/free/ContravariantCoyoneda.scala index e122fb283e..92c6b47f30 100644 --- a/free/src/main/scala/cats/free/ContravariantCoyoneda.scala +++ b/free/src/main/scala/cats/free/ContravariantCoyoneda.scala @@ -25,9 +25,9 @@ package free import cats.data.AndThen /** - * The free contravariant functor on `F`. This is isomorphic to `F` as long as `F` itself is a - * contravariant functor. The function from `F[A]` to `ContravariantCoyoneda[F,A]` exists even when - * `F` is not a contravariant functor. Implemented using a List of functions for stack-safety. + * The free contravariant functor on `F`. This is isomorphic to `F` as long as `F` itself is a contravariant functor. + * The function from `F[A]` to `ContravariantCoyoneda[F,A]` exists even when `F` is not a contravariant functor. + * Implemented using a List of functions for stack-safety. */ sealed abstract class ContravariantCoyoneda[F[_], A] extends Serializable { self => import ContravariantCoyoneda.Aux @@ -75,8 +75,7 @@ sealed abstract class ContravariantCoyoneda[F[_], A] extends Serializable { self object ContravariantCoyoneda { /** - * Lift the `Pivot` type member to a parameter. It is usually more convenient to use `Aux` than - * a refinment type. + * Lift the `Pivot` type member to a parameter. It is usually more convenient to use `Aux` than a refinment type. */ type Aux[F[_], A, B] = ContravariantCoyoneda[F, A] { type Pivot = B } diff --git a/free/src/main/scala/cats/free/Coyoneda.scala b/free/src/main/scala/cats/free/Coyoneda.scala index 49679c4e1f..55020fffdc 100644 --- a/free/src/main/scala/cats/free/Coyoneda.scala +++ b/free/src/main/scala/cats/free/Coyoneda.scala @@ -26,11 +26,9 @@ import cats.arrow.FunctionK import cats.data.AndThen /** - * The dual view of the Yoneda lemma. The free functor on `F`. - * This is isomorphic to `F` as long as `F` itself is a functor. - * The function from `F[A]` to `Coyoneda[F,A]` exists even when - * `F` is not a functor. - * Implemented using a List of functions for stack-safety. + * The dual view of the Yoneda lemma. The free functor on `F`. This is isomorphic to `F` as long as `F` itself is a + * functor. The function from `F[A]` to `Coyoneda[F,A]` exists even when `F` is not a functor. Implemented using a List + * of functions for stack-safety. */ sealed abstract class Coyoneda[F[_], A] extends Serializable { self => @@ -71,8 +69,7 @@ sealed abstract class Coyoneda[F[_], A] extends Serializable { self => } /** - * Simple function composition. Allows map fusion without touching - * the underlying `F`. + * Simple function composition. Allows map fusion without touching the underlying `F`. */ final def map[B](f: A => B): Aux[F, B, Pivot] = Coyoneda(fi)(AndThen(k).andThen(f)) @@ -92,8 +89,7 @@ sealed abstract class Coyoneda[F[_], A] extends Serializable { self => object Coyoneda { /** - * Lift the `Pivot` type member to a parameter. It is usually more - * convenient to use `Aux` than a structural type. + * Lift the `Pivot` type member to a parameter. It is usually more convenient to use `Aux` than a structural type. */ type Aux[F[_], A, B] = Coyoneda[F, A] { type Pivot = B } diff --git a/free/src/main/scala/cats/free/Free.scala b/free/src/main/scala/cats/free/Free.scala index ff79120787..15f5787c1a 100644 --- a/free/src/main/scala/cats/free/Free.scala +++ b/free/src/main/scala/cats/free/Free.scala @@ -27,9 +27,8 @@ import scala.annotation.tailrec import cats.arrow.FunctionK /** - * A free operational monad for some functor `S`. Binding is done - * using the heap instead of the stack, allowing tail-call - * elimination. + * A free operational monad for some functor `S`. Binding is done using the heap instead of the stack, allowing + * tail-call elimination. */ sealed abstract class Free[S[_], A] extends Product with Serializable with FreeFoldStep[S, A] { @@ -41,12 +40,10 @@ sealed abstract class Free[S[_], A] extends Product with Serializable with FreeF /** * Modify the functor context `S` using transformation `f`. * - * This is effectively compiling your free monad into another - * language by changing the suspension functor using the given - * natural transformation `f`. + * This is effectively compiling your free monad into another language by changing the suspension functor using the + * given natural transformation `f`. * - * If your natural transformation is effectful, be careful. These - * effects will be applied by `mapK`. + * If your natural transformation is effectful, be careful. These effects will be applied by `mapK`. */ final def mapK[T[_]](f: S ~> T): Free[T, A] = foldMap[Free[T, *]] { // this is safe because Free is stack safe @@ -54,15 +51,14 @@ sealed abstract class Free[S[_], A] extends Product with Serializable with FreeF } /** - * Bind the given continuation to the result of this computation. - * All left-associated binds are reassociated to the right. + * Bind the given continuation to the result of this computation. All left-associated binds are reassociated to the + * right. */ final def flatMap[B](f: A => Free[S, B]): Free[S, B] = FlatMapped(this, f) /** - * Catamorphism. Run the first given function if Pure, otherwise, - * the second given function. + * Catamorphism. Run the first given function if Pure, otherwise, the second given function. */ final def fold[B](r: A => B, s: S[Free[S, A]] => B)(implicit S: Functor[S]): B = resume.fold(s, r) @@ -95,8 +91,7 @@ sealed abstract class Free[S[_], A] extends Product with Serializable with FreeF } /** - * Run to completion, using a function that extracts the resumption - * from its suspension functor. + * Run to completion, using a function that extracts the resumption from its suspension functor. */ final def go(f: S[Free[S, A]] => Free[S, A])(implicit S: Functor[S]): A = { @tailrec def loop(t: Free[S, A]): A = @@ -108,15 +103,13 @@ sealed abstract class Free[S[_], A] extends Product with Serializable with FreeF } /** - * Run to completion, using the given comonad to extract the - * resumption. + * Run to completion, using the given comonad to extract the resumption. */ final def run(implicit S: Comonad[S]): A = go(S.extract) /** - * Run to completion, using a function that maps the resumption - * from `S` to a monad `M`. + * Run to completion, using a function that maps the resumption from `S` to a monad `M`. */ final def runM[M[_]](f: S[Free[S, A]] => M[Free[S, A]])(implicit S: Functor[S], M: Monad[M]): M[A] = { def step(t: S[Free[S, A]]): M[Either[S[Free[S, A]], A]] = @@ -129,8 +122,7 @@ sealed abstract class Free[S[_], A] extends Product with Serializable with FreeF } /** - * Run to completion, using monadic recursion to evaluate the - * resumption in the context of `S`. + * Run to completion, using monadic recursion to evaluate the resumption in the context of `S`. */ final def runTailRec(implicit S: Monad[S]): S[A] = { def step(rma: Free[S, A]): S[Either[Free[S, A], A]] = @@ -155,8 +147,8 @@ sealed abstract class Free[S[_], A] extends Product with Serializable with FreeF /** * Catamorphism for `Free`. * - * Run to completion, mapping the suspension with the given - * transformation at each step and accumulating into the monad `M`. + * Run to completion, mapping the suspension with the given transformation at each step and accumulating into the + * monad `M`. * * This method uses `tailRecM` to provide stack-safety. */ @@ -168,17 +160,16 @@ sealed abstract class Free[S[_], A] extends Product with Serializable with FreeF }) /** - * Compile your free monad into another language by changing the - * suspension functor using the given natural transformation `f`. + * Compile your free monad into another language by changing the suspension functor using the given natural + * transformation `f`. * - * If your natural transformation is effectful, be careful. These - * effects will be applied by `compile`. + * If your natural transformation is effectful, be careful. These effects will be applied by `compile`. */ final def compile[T[_]](f: FunctionK[S, T]): Free[T, A] = mapK(f) /** - * Lift into `G` (typically a `EitherK`) given `InjectK`. Analogous - * to `Free.inject` but lifts programs rather than constructors. + * Lift into `G` (typically a `EitherK`) given `InjectK`. Analogous to `Free.inject` but lifts programs rather than + * constructors. * * {{{ * scala> type Lo[A] = cats.data.EitherK[List, Option, A] @@ -290,19 +281,19 @@ object Free extends FreeInstances { new FunctionK[Free[F, *], M] { def apply[A](f: Free[F, A]): M[A] = f.foldMap(fk) } /** - * This method is used to defer the application of an InjectK[F, G] - * instance. The actual work happens in + * This method is used to defer the application of an InjectK[F, G] instance. The actual work happens in * `FreeInjectKPartiallyApplied#apply`. * - * This method exists to allow the `F` and `G` parameters to be - * bound independently of the `A` parameter below. + * This method exists to allow the `F` and `G` parameters to be bound independently of the `A` parameter below. */ @deprecated("use liftInject", "2.3.1") def inject[F[_], G[_]]: FreeInjectKPartiallyApplied[F, G] = new FreeInjectKPartiallyApplied /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[free] class FreeInjectKPartiallyApplied[F[_], G[_]](private val dummy: Boolean = true) extends AnyVal { def apply[A](fa: F[A])(implicit I: InjectK[F, G]): Free[G, A] = @@ -310,18 +301,18 @@ object Free extends FreeInstances { } /** - * This method is used to defer the application of an InjectK[F, G] - * instance. The actual work happens in + * This method is used to defer the application of an InjectK[F, G] instance. The actual work happens in * `FreeLiftInjectKPartiallyApplied#apply`. * - * This method exists to allow the `G` parameter to be - * bound independently of the `F` and `A` parameters below. + * This method exists to allow the `G` parameter to be bound independently of the `F` and `A` parameters below. */ def liftInject[G[_]]: FreeLiftInjectKPartiallyApplied[G] = new FreeLiftInjectKPartiallyApplied /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[free] class FreeLiftInjectKPartiallyApplied[G[_]](private val dummy: Boolean = true) extends AnyVal { def apply[F[_], A](fa: F[A])(implicit I: InjectK[F, G]): Free[G, A] = diff --git a/free/src/main/scala/cats/free/FreeApplicative.scala b/free/src/main/scala/cats/free/FreeApplicative.scala index 78f733cf1d..fc44de4e29 100644 --- a/free/src/main/scala/cats/free/FreeApplicative.scala +++ b/free/src/main/scala/cats/free/FreeApplicative.scala @@ -28,8 +28,7 @@ import cats.data.Const import scala.annotation.tailrec /** - * Applicative Functor for Free, - * implementation inspired by https://github.com/safareli/free/pull/31/ + * Applicative Functor for Free, implementation inspired by https://github.com/safareli/free/pull/31/ */ sealed abstract class FreeApplicative[F[_], A] extends Product with Serializable { self => @@ -61,8 +60,7 @@ sealed abstract class FreeApplicative[F[_], A] extends Product with Serializable } /** - * Interprets/Runs the sequence of operations using the semantics of `Applicative` G[_]. - * Tail recursive. + * Interprets/Runs the sequence of operations using the semantics of `Applicative` G[_]. Tail recursive. */ final def foldMap[G[_]](f: F ~> G)(implicit G: Applicative[G]): G[A] = { import FreeApplicative.* @@ -148,15 +146,13 @@ sealed abstract class FreeApplicative[F[_], A] extends Product with Serializable } /** - * Interpret/run the operations using the semantics of `Applicative[F]`. - * Stack-safe. + * Interpret/run the operations using the semantics of `Applicative[F]`. Stack-safe. */ final def fold(implicit F: Applicative[F]): F[A] = foldMap(FunctionK.id[F]) /** - * Interpret this algebra into another algebra. - * Stack-safe. + * Interpret this algebra into another algebra. Stack-safe. */ final def compile[G[_]](f: F ~> G): FA[G, A] = foldMap[FA[G, *]] { @@ -164,8 +160,7 @@ sealed abstract class FreeApplicative[F[_], A] extends Product with Serializable } /** - * Interpret this algebra into a FreeApplicative over another algebra. - * Stack-safe. + * Interpret this algebra into a FreeApplicative over another algebra. Stack-safe. */ def flatCompile[G[_]](f: F ~> FA[G, *]): FA[G, A] = foldMap(f) @@ -201,9 +196,8 @@ object FreeApplicative { } /** - * Represents a curried function `F[A => B => C => ...]` - * that has been constructed with chained `ap` calls. - * Fn#argc denotes the amount of curried params remaining. + * Represents a curried function `F[A => B => C => ...]` that has been constructed with chained `ap` calls. Fn#argc + * denotes the amount of curried params remaining. */ final private case class Fn[G[_], A, B](gab: G[A => B], argc: Int) diff --git a/free/src/main/scala/cats/free/FreeT.scala b/free/src/main/scala/cats/free/FreeT.scala index a447a7af15..097ddcf09b 100644 --- a/free/src/main/scala/cats/free/FreeT.scala +++ b/free/src/main/scala/cats/free/FreeT.scala @@ -54,8 +54,7 @@ sealed abstract class FreeT[S[_], M[_], A] extends Product with Serializable { } /** - * Modify the context `M` using the transformation `mn`, flattening the free - * suspensions into the outer. + * Modify the context `M` using the transformation `mn`, flattening the free suspensions into the outer. */ def flatMapK[N[_]](mn: M ~> FreeT[S, N, *])(implicit S: Functor[S], N: Monad[N]): FreeT[S, N, A] = { def loop(ftft: FreeT[S, FreeT[S, N, *], A]): FreeT[S, N, A] = @@ -73,8 +72,7 @@ sealed abstract class FreeT[S[_], M[_], A] extends Product with Serializable { FlatMapped(this, f) /** - * Changes the underlying `Monad` for this `FreeT`, ie. - * turning this `FreeT[S, M, A]` into a `FreeT[S, N, A]`. + * Changes the underlying `Monad` for this `FreeT`, ie. turning this `FreeT[S, M, A]` into a `FreeT[S, N, A]`. */ def hoist[N[_]](mn: FunctionK[M, N]): FreeT[S, N, A] = mapK(mn) @@ -94,8 +92,8 @@ sealed abstract class FreeT[S[_], M[_], A] extends Product with Serializable { } /** - * Runs to completion, mapping the suspension with the given transformation - * at each step and accumulating into the monad `M`. + * Runs to completion, mapping the suspension with the given transformation at each step and accumulating into the + * monad `M`. */ def foldMap(f: FunctionK[S, M])(implicit M: Monad[M]): M[A] = { def go(ft: FreeT[S, M, A]): M[Either[FreeT[S, M, A], A]] = @@ -153,9 +151,8 @@ sealed abstract class FreeT[S[_], M[_], A] extends Product with Serializable { } /** - * Finds the first `M` instance, `m`, and maps it to contain the rest - * of the computation. Since only `map` is used on `m`, its structure - * is preserved. + * Finds the first `M` instance, `m`, and maps it to contain the rest of the computation. Since only `map` is used on + * `m`, its structure is preserved. */ @tailrec final private[cats] def toM(implicit M: Applicative[M]): M[FreeT[S, M, A]] = @@ -247,18 +244,19 @@ object FreeT extends FreeTInstances { new FunctionK[FreeT[S, M, *], M] { def apply[A](f: FreeT[S, M, A]): M[A] = f.foldMap(fk) } /** - * This method is used to defer the application of an InjectK[F, G] - * instance. The actual work happens in + * This method is used to defer the application of an InjectK[F, G] instance. The actual work happens in * `FreeTLiftInjectKPartiallyApplied#apply`. * - * This method exists to allow the `M` and `G` parameters to be - * bound independently of the `F` and `A` parameters below. + * This method exists to allow the `M` and `G` parameters to be bound independently of the `F` and `A` parameters + * below. */ def liftInject[M[_], G[_]]: FreeTLiftInjectKPartiallyApplied[M, G] = new FreeTLiftInjectKPartiallyApplied /** - * Uses the [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] for ergonomics. + * Uses the + * [[http://typelevel.org/cats/guidelines.html#partially-applied-type-params Partially Applied Type Params technique]] + * for ergonomics. */ final private[free] class FreeTLiftInjectKPartiallyApplied[M[_], G[_]](private val dummy: Boolean = true) extends AnyVal { diff --git a/free/src/main/scala/cats/free/InvariantCoyoneda.scala b/free/src/main/scala/cats/free/InvariantCoyoneda.scala index a7d97f9501..16627c5d53 100644 --- a/free/src/main/scala/cats/free/InvariantCoyoneda.scala +++ b/free/src/main/scala/cats/free/InvariantCoyoneda.scala @@ -25,9 +25,9 @@ package free import cats.data.AndThen /** - * The free invariant functor on `F`. This is isomorphic to `F` as long as `F` itself is a - * invariant functor. The function from `F[A]` to `InvariantCoyoneda[F,A]` exists even when - * `F` is not an invariant functor. Implemented using a List of functions for stack-safety. + * The free invariant functor on `F`. This is isomorphic to `F` as long as `F` itself is a invariant functor. The + * function from `F[A]` to `InvariantCoyoneda[F,A]` exists even when `F` is not an invariant functor. Implemented using + * a List of functions for stack-safety. */ sealed abstract class InvariantCoyoneda[F[_], A] extends Serializable { self => import InvariantCoyoneda.Aux @@ -80,8 +80,7 @@ sealed abstract class InvariantCoyoneda[F[_], A] extends Serializable { self => object InvariantCoyoneda { /** - * Lift the `Pivot` type member to a parameter. It is usually more convenient to use `Aux` than - * a refinment type. + * Lift the `Pivot` type member to a parameter. It is usually more convenient to use `Aux` than a refinment type. */ type Aux[F[_], A, B] = InvariantCoyoneda[F, A] { type Pivot = B } diff --git a/free/src/main/scala/cats/free/Yoneda.scala b/free/src/main/scala/cats/free/Yoneda.scala index b8d702ff8e..ccf0ffc7f1 100644 --- a/free/src/main/scala/cats/free/Yoneda.scala +++ b/free/src/main/scala/cats/free/Yoneda.scala @@ -23,11 +23,9 @@ package cats package free /** - * The cofree functor for `F`. The Yoneda lemma says that - * `Yoneda[F,A]` is isomorphic to `F[A]` for any functor `F`. - * The function from `Yoneda[F, A]` to `F[A]` exists even when - * we have forgotten that `F` is a functor. - * Can be seen as a partially applied `map` for the functor `F`. + * The cofree functor for `F`. The Yoneda lemma says that `Yoneda[F,A]` is isomorphic to `F[A]` for any functor `F`. The + * function from `Yoneda[F, A]` to `F[A]` exists even when we have forgotten that `F` is a functor. Can be seen as a + * partially applied `map` for the functor `F`. */ abstract class Yoneda[F[_], A] extends Serializable { self => def apply[B](f: A => B): F[B] diff --git a/kernel-laws/shared/src/main/scala/cats/kernel/laws/SerializableLaws.scala b/kernel-laws/shared/src/main/scala/cats/kernel/laws/SerializableLaws.scala index bbd3e34c35..85c25df83b 100644 --- a/kernel-laws/shared/src/main/scala/cats/kernel/laws/SerializableLaws.scala +++ b/kernel-laws/shared/src/main/scala/cats/kernel/laws/SerializableLaws.scala @@ -30,9 +30,8 @@ import scala.util.control.NonFatal /** * Check for Java Serializability. * - * This law is only applicable on the JVM, but is something we want - * to be sure to enforce. Therefore, we use bricks.Platform to do a - * runtime check rather than create a separate jvm-laws project. + * This law is only applicable on the JVM, but is something we want to be sure to enforce. Therefore, we use + * bricks.Platform to do a runtime check rather than create a separate jvm-laws project. */ object SerializableLaws { diff --git a/kernel/src/main/scala/cats/kernel/Band.scala b/kernel/src/main/scala/cats/kernel/Band.scala index 9ab3d8d05a..d5c44a9009 100644 --- a/kernel/src/main/scala/cats/kernel/Band.scala +++ b/kernel/src/main/scala/cats/kernel/Band.scala @@ -24,8 +24,7 @@ package cats.kernel import scala.{specialized => sp} /** - * Bands are semigroups whose operation - * (i.e. combine) is also idempotent. + * Bands are semigroups whose operation (i.e. combine) is also idempotent. */ trait Band[@sp(Int, Long, Float, Double) A] extends Any with Semigroup[A] { override protected[this] def repeatedCombineN(a: A, n: Int): A = diff --git a/kernel/src/main/scala/cats/kernel/CommutativeGroup.scala b/kernel/src/main/scala/cats/kernel/CommutativeGroup.scala index ed5750d4fa..fabce00f53 100644 --- a/kernel/src/main/scala/cats/kernel/CommutativeGroup.scala +++ b/kernel/src/main/scala/cats/kernel/CommutativeGroup.scala @@ -24,8 +24,7 @@ package cats.kernel import scala.{specialized => sp} /** - * An commutative group (also known as an abelian group) is a group - * whose combine operation is commutative. + * An commutative group (also known as an abelian group) is a group whose combine operation is commutative. */ trait CommutativeGroup[@sp(Int, Long, Float, Double) A] extends Any with Group[A] with CommutativeMonoid[A] diff --git a/kernel/src/main/scala/cats/kernel/Enumerable.scala b/kernel/src/main/scala/cats/kernel/Enumerable.scala index d287113d27..f98a983d77 100644 --- a/kernel/src/main/scala/cats/kernel/Enumerable.scala +++ b/kernel/src/main/scala/cats/kernel/Enumerable.scala @@ -25,8 +25,7 @@ package kernel import scala.{specialized => sp} /** - * A typeclass with an operation which returns a member which is - * greater or `None` than the one supplied. + * A typeclass with an operation which returns a member which is greater or `None` than the one supplied. */ trait PartialNext[@sp A] { def partialOrder: PartialOrder[A] @@ -34,8 +33,7 @@ trait PartialNext[@sp A] { } /** - * A typeclass with an operation which returns a member which is - * always greater than the one supplied. + * A typeclass with an operation which returns a member which is always greater than the one supplied. */ trait Next[@sp A] extends PartialNext[A] { def next(a: A): A @@ -43,8 +41,7 @@ trait Next[@sp A] extends PartialNext[A] { } /** - * A typeclass with an operation which returns a member which is - * smaller or `None` than the one supplied. + * A typeclass with an operation which returns a member which is smaller or `None` than the one supplied. */ trait PartialPrevious[@sp A] { def partialOrder: PartialOrder[A] @@ -52,8 +49,7 @@ trait PartialPrevious[@sp A] { } /** - * A typeclass with an operation which returns a member which is - * always smaller than the one supplied. + * A typeclass with an operation which returns a member which is always smaller than the one supplied. */ trait Previous[@sp A] extends PartialPrevious[A] { def partialOrder: PartialOrder[A] @@ -62,8 +58,7 @@ trait Previous[@sp A] extends PartialPrevious[A] { } /** - * A typeclass which has both `previous` and `next` operations - * such that `next . previous == identity`. + * A typeclass which has both `previous` and `next` operations such that `next . previous == identity`. */ trait UnboundedEnumerable[@sp A] extends Next[A] with Previous[A] { def order: Order[A] @@ -102,8 +97,8 @@ object BoundedEnumerable { @inline def apply[A](implicit e: BoundedEnumerable[A]): BoundedEnumerable[A] = e /** - * Defines a `BoundedEnumerable[A]` from the given enumerable such that - * all arrows / successor functions switch direction. + * Defines a `BoundedEnumerable[A]` from the given enumerable such that all arrows / successor functions switch + * direction. */ def reverse[@sp A](e: BoundedEnumerable[A]): BoundedEnumerable[A] = new BoundedEnumerable[A] { diff --git a/kernel/src/main/scala/cats/kernel/Eq.scala b/kernel/src/main/scala/cats/kernel/Eq.scala index 5be5333e0a..20e1be089e 100644 --- a/kernel/src/main/scala/cats/kernel/Eq.scala +++ b/kernel/src/main/scala/cats/kernel/Eq.scala @@ -30,9 +30,8 @@ import scala.util.{Failure, Success, Try} import scala.{specialized => sp} /** - * A type class used to determine equality between 2 instances of the same - * type. Any 2 instances `x` and `y` are equal if `eqv(x, y)` is `true`. - * Moreover, `eqv` should form an equivalence relation. + * A type class used to determine equality between 2 instances of the same type. Any 2 instances `x` and `y` are equal + * if `eqv(x, y)` is `true`. Moreover, `eqv` should form an equivalence relation. */ trait Eq[@sp A] extends Any with Serializable { self => @@ -59,8 +58,7 @@ abstract class EqFunctions[E[T] <: Eq[T]] { trait EqToEquivConversion { /** - * Implicitly derive a `scala.math.Equiv[A]` from a `Eq[A]` - * instance. + * Implicitly derive a `scala.math.Equiv[A]` from a `Eq[A]` instance. */ implicit def catsKernelEquivForEq[A](implicit ev: Eq[A]): Equiv[A] = ev.eqv(_, _) @@ -80,22 +78,19 @@ object Eq @inline final def apply[A](implicit ev: Eq[A]): Eq[A] = ev /** - * Convert an implicit `Eq[B]` to an `Eq[A]` using the given - * function `f`. + * Convert an implicit `Eq[B]` to an `Eq[A]` using the given function `f`. */ def by[@sp A, @sp B](f: A => B)(implicit ev: Eq[B]): Eq[A] = (x, y) => ev.eqv(f(x), f(y)) /** - * Return an Eq that gives the result of the and of eq1 and eq2 - * note this is idempotent + * Return an Eq that gives the result of the and of eq1 and eq2 note this is idempotent */ def and[@sp A](eq1: Eq[A], eq2: Eq[A]): Eq[A] = (x, y) => eq1.eqv(x, y) && eq2.eqv(x, y) /** - * Return an Eq that gives the result of the or of this and that - * Note this is idempotent + * Return an Eq that gives the result of the or of this and that Note this is idempotent */ def or[@sp A](eq1: Eq[A], eq2: Eq[A]): Eq[A] = (x, y) => eq1.eqv(x, y) || eq2.eqv(x, y) @@ -108,8 +103,7 @@ object Eq /** * An `Eq[A]` that delegates to universal equality (`==`). * - * This can be useful for case classes, which have reasonable `equals` - * implementations + * This can be useful for case classes, which have reasonable `equals` implementations */ def fromUniversalEquals[A]: Eq[A] = _ == _ @@ -119,8 +113,7 @@ object Eq def allEqual[A]: Eq[A] = (_, _) => true /** - * This is a monoid that creates an Eq that - * checks that all equality checks pass + * This is a monoid that creates an Eq that checks that all equality checks pass */ def allEqualBoundedSemilattice[A]: BoundedSemilattice[Eq[A]] = new BoundedSemilattice[Eq[A]] { @@ -135,8 +128,7 @@ object Eq } /** - * This is a monoid that creates an Eq that - * checks that at least one equality check passes + * This is a monoid that creates an Eq that checks that at least one equality check passes */ def anyEqualSemilattice[A]: Semilattice[Eq[A]] = new Semilattice[Eq[A]] { @@ -202,9 +194,8 @@ object Eq cats.kernel.instances.function.catsKernelOrderForFunction0[A] /** - * you may wish to do equality by making `implicit val eqT: Eq[Throwable] = Eq.allEqual` - * doing a fine grained equality on Throwable can make the code very execution - * order dependent + * you may wish to do equality by making `implicit val eqT: Eq[Throwable] = Eq.allEqual` doing a fine grained equality + * on Throwable can make the code very execution order dependent */ implicit def catsStdEqForTry[A](implicit A: Eq[A], T: Eq[Throwable]): Eq[Try[A]] = { case (Success(a), Success(b)) => A.eqv(a, b) diff --git a/kernel/src/main/scala/cats/kernel/Group.scala b/kernel/src/main/scala/cats/kernel/Group.scala index 0cc026e524..c124ab5b7b 100644 --- a/kernel/src/main/scala/cats/kernel/Group.scala +++ b/kernel/src/main/scala/cats/kernel/Group.scala @@ -59,8 +59,8 @@ trait Group[@sp(Int, Long, Float, Double) A] extends Any with Monoid[A] { def remove(a: A, b: A): A = combine(a, inverse(b)) /** - * Return `a` appended to itself `n` times. If `n` is negative, then - * this returns `inverse(a)` appended to itself `n` times. + * Return `a` appended to itself `n` times. If `n` is negative, then this returns `inverse(a)` appended to itself `n` + * times. */ override def combineN(a: A, n: Int): A = // This method is a bit tricky. Normally, to sum x a negative diff --git a/kernel/src/main/scala/cats/kernel/Hash.scala b/kernel/src/main/scala/cats/kernel/Hash.scala index 02bb7252ba..a3f4ec72e9 100644 --- a/kernel/src/main/scala/cats/kernel/Hash.scala +++ b/kernel/src/main/scala/cats/kernel/Hash.scala @@ -25,10 +25,10 @@ import scala.{specialized => sp} import scala.util.hashing.Hashing /** - * A type class used to represent a hashing scheme for objects of a given type. - * For any two instances `x` and `y` that are considered equivalent under the - * equivalence relation defined by this object, `hash(x)` should equal `hash(y)`. - * @author Tongfei Chen + * A type class used to represent a hashing scheme for objects of a given type. For any two instances `x` and `y` that + * are considered equivalent under the equivalence relation defined by this object, `hash(x)` should equal `hash(y)`. + * @author + * Tongfei Chen */ trait Hash[@sp A] extends Any with Eq[A] with Serializable { self => diff --git a/kernel/src/main/scala/cats/kernel/Monoid.scala b/kernel/src/main/scala/cats/kernel/Monoid.scala index 5856ddf726..09799df975 100644 --- a/kernel/src/main/scala/cats/kernel/Monoid.scala +++ b/kernel/src/main/scala/cats/kernel/Monoid.scala @@ -25,9 +25,8 @@ import scala.{specialized => sp} import compat.scalaVersionSpecific.* /** - * A monoid is a semigroup with an identity. A monoid is a specialization of a - * semigroup, so its operation must be associative. Additionally, - * `combine(x, empty) == combine(empty, x) == x`. For example, if we have `Monoid[String]`, + * A monoid is a semigroup with an identity. A monoid is a specialization of a semigroup, so its operation must be + * associative. Additionally, `combine(x, empty) == combine(empty, x) == x`. For example, if we have `Monoid[String]`, * with `combine` as string concatenation, then `empty = ""`. */ trait Monoid[@sp(Int, Long, Float, Double) A] extends Any with Semigroup[A] { self => diff --git a/kernel/src/main/scala/cats/kernel/Order.scala b/kernel/src/main/scala/cats/kernel/Order.scala index db26f4bc48..0602013462 100644 --- a/kernel/src/main/scala/cats/kernel/Order.scala +++ b/kernel/src/main/scala/cats/kernel/Order.scala @@ -24,19 +24,20 @@ package cats.kernel import scala.{specialized => sp} /** - * The `Order` type class is used to define a total ordering on some type `A`. - * An order is defined by a relation <=, which obeys the following laws: + * The `Order` type class is used to define a total ordering on some type `A`. An order is defined by a relation <=, + * which obeys the following laws: * - * - either x <= y or y <= x (totality) - * - if x <= y and y <= x, then x == y (antisymmetry) - * - if x <= y and y <= z, then x <= z (transitivity) + * - either x <= y or y <= x (totality) + * - if x <= y and y <= x, then x == y (antisymmetry) + * - if x <= y and y <= z, then x <= z (transitivity) * * The truth table for compare is defined as follows: * - * x <= y x >= y Int - * true true = 0 (corresponds to x == y) - * true false < 0 (corresponds to x < y) - * false true > 0 (corresponds to x > y) + * | x <= y | x >= y | Int | | + * |:-------|:-------|:----|:------------------------| + * | true | true | = 0 | (corresponds to x == y) | + * | true | false | < 0 | (corresponds to x < y) | + * | false | true | > 0 | (corresponds to x > y) | * * By the totality law, x <= y and y <= x cannot be both false. */ @@ -44,15 +45,15 @@ trait Order[@sp A] extends Any with PartialOrder[A] { self => /** * Result of comparing `x` with `y`. Returns an Int whose sign is: - * - negative iff `x < y` - * - zero iff `x = y` - * - positive iff `x > y` + * - negative iff `x < y` + * - zero iff `x = y` + * - positive iff `x > y` */ def compare(x: A, y: A): Int /** - * Like `compare`, but returns a [[cats.kernel.Comparison]] instead of an Int. - * Has the benefit of being able to pattern match on, but not as performant. + * Like `compare`, but returns a [[cats.kernel.Comparison]] instead of an Int. Has the benefit of being able to + * pattern match on, but not as performant. */ def comparison(x: A, y: A): Comparison = Comparison.fromInt(compare(x, y)) @@ -79,10 +80,9 @@ trait Order[@sp A] extends Any with PartialOrder[A] { self => /** * Returns true if `x` != `y`, false otherwise. * - * Note: this default implementation provided by [[Order]] is the same as the - * one defined in [[Eq]], but for purposes of binary compatibility, the - * override in [[Order]] has not yet been removed. - * See [[https://github.com/typelevel/cats/pull/2230#issuecomment-381818633 this discussion]]. + * Note: this default implementation provided by [[Order]] is the same as the one defined in [[Eq]], but for purposes + * of binary compatibility, the override in [[Order]] has not yet been removed. See + * [[https://github.com/typelevel/cats/pull/2230#issuecomment-381818633 this discussion]]. */ override def neqv(x: A, y: A): Boolean = !eqv(x, y) @@ -111,8 +111,7 @@ trait Order[@sp A] extends Any with PartialOrder[A] { self => compare(x, y) > 0 /** - * Convert a `Order[A]` to a `scala.math.Ordering[A]` - * instance. + * Convert a `Order[A]` to a `scala.math.Ordering[A]` instance. */ def toOrdering: Ordering[A] = compare(_, _) @@ -136,8 +135,7 @@ abstract class OrderFunctions[O[T] <: Order[T]] extends PartialOrderFunctions[O] trait OrderToOrderingConversion { /** - * Implicitly derive a `scala.math.Ordering[A]` from a `Order[A]` - * instance. + * Implicitly derive a `scala.math.Ordering[A]` from a `Order[A]` instance. */ implicit def catsKernelOrderingForOrder[A](implicit ev: Order[A]): Ordering[A] = ev.toOrdering @@ -152,8 +150,7 @@ object Order extends OrderFunctions[Order] with OrderToOrderingConversion { @inline final def apply[A](implicit ev: Order[A]): Order[A] = ev /** - * Convert an implicit `Order[B]` to an `Order[A]` using the given - * function `f`. + * Convert an implicit `Order[B]` to an `Order[A]` using the given function `f`. */ def by[@sp A, @sp B](f: A => B)(implicit ev: Order[B]): Order[A] = (x, y) => ev.compare(f(x), f(y)) @@ -165,11 +162,11 @@ object Order extends OrderFunctions[Order] with OrderToOrderingConversion { (x, y) => order.compare(y, x) /** - * Returns a new `Order[A]` instance that first compares by the first - * `Order` instance and uses the second `Order` instance to "break ties". + * Returns a new `Order[A]` instance that first compares by the first `Order` instance and uses the second `Order` + * instance to "break ties". * - * That is, `Order.whenEqual(x, y)` creates an `Order` that first orders by `x` and - * then (if two elements are equal) falls back to `y` for the comparison. + * That is, `Order.whenEqual(x, y)` creates an `Order` that first orders by `x` and then (if two elements are equal) + * falls back to `y` for the comparison. */ def whenEqual[@sp A](first: Order[A], second: Order[A]): Order[A] = { (x, y) => val c = first.compare(x, y) @@ -206,19 +203,17 @@ object Order extends OrderFunctions[Order] with OrderToOrderingConversion { (_, _) => 0 /** - * A `Monoid[Order[A]]` can be generated for all `A` with the following - * properties: + * A `Monoid[Order[A]]` can be generated for all `A` with the following properties: * - * `empty` returns a trivial `Order[A]` which considers all `A` instances to - * be equal. + * `empty` returns a trivial `Order[A]` which considers all `A` instances to be equal. * - * `combine(x: Order[A], y: Order[A])` creates an `Order[A]` that first - * orders by `x` and then (if two elements are equal) falls back to `y`. + * `combine(x: Order[A], y: Order[A])` creates an `Order[A]` that first orders by `x` and then (if two elements are + * equal) falls back to `y`. * - * This monoid is also a `Band[Order[A]]` since its combine - * operations is idempotent. + * This monoid is also a `Band[Order[A]]` since its combine operations is idempotent. * - * @see [[Order.whenEqual]] + * @see + * [[Order.whenEqual]] */ def whenEqualMonoid[A]: Monoid[Order[A]] & Band[Order[A]] = new Monoid[Order[A]] with Band[Order[A]] { diff --git a/kernel/src/main/scala/cats/kernel/PartialOrder.scala b/kernel/src/main/scala/cats/kernel/PartialOrder.scala index 1b126777a6..8208fe2e61 100644 --- a/kernel/src/main/scala/cats/kernel/PartialOrder.scala +++ b/kernel/src/main/scala/cats/kernel/PartialOrder.scala @@ -34,44 +34,41 @@ import compat.scalaVersionSpecific.* * - if x <= y and y <= x, then x = y (anti-symmetry) * - if x <= y and y <= z, then x <= z (transitivity) * - * To compute both <= and >= at the same time, we use a Double number - * to encode the result of the comparisons x <= y and x >= y. - * The truth table is defined as follows: + * To compute both <= and >= at the same time, we use a Double number to encode the result of the comparisons x <= y and + * x >= y. The truth table is defined as follows: * - * | x <= y | x >= y | result | note | - * | :-- | :-- | --: | :-- | - * | true |true | 0.0 | (corresponds to x = y) | - * | false |false | NaN | (x and y cannot be compared) | - * | true |false | -1.0 | (corresponds to x < y) | - * | false |true | 1.0 | (corresponds to x > y) | + * | x <= y | x >= y | result | note | + * |:-------|:-------|-------:|:-----------------------------| + * | true | true | 0.0 | (corresponds to x = y) | + * | false | false | NaN | (x and y cannot be compared) | + * | true | false | -1.0 | (corresponds to x < y) | + * | false | true | 1.0 | (corresponds to x > y) | */ trait PartialOrder[@sp A] extends Any with Eq[A] { self => /** - * Result of comparing `x` with `y`. Returns NaN if operands are not - * comparable. If operands are comparable, returns a Double whose - * sign is: + * Result of comparing `x` with `y`. Returns NaN if operands are not comparable. If operands are comparable, returns a + * Double whose sign is: * * - negative iff `x < y` - * - zero iff `x = y` + * - zero iff `x = y` * - positive iff `x > y` */ def partialCompare(x: A, y: A): Double /** - * Like `partialCompare`, but returns a [[cats.kernel.Comparison]] instead of an Double. - * Has the benefit of being able to pattern match on, but not as performant. + * Like `partialCompare`, but returns a [[cats.kernel.Comparison]] instead of an Double. Has the benefit of being able + * to pattern match on, but not as performant. */ def partialComparison(x: A, y: A): Option[Comparison] = Comparison.fromDouble(partialCompare(x, y)) /** - * Result of comparing `x` with `y`. Returns None if operands are - * not comparable. If operands are comparable, returns Some[Int] - * where the Int sign is: + * Result of comparing `x` with `y`. Returns None if operands are not comparable. If operands are comparable, returns + * Some[Int] where the Int sign is: * * - negative iff `x < y` - * - zero iff `x = y` + * - zero iff `x = y` * - positive iff `x > y` */ def tryCompare(x: A, y: A): Option[Int] = { @@ -158,8 +155,7 @@ object PartialOrder extends PartialOrderFunctions[PartialOrder] with PartialOrde @inline final def apply[A](implicit ev: PartialOrder[A]): PartialOrder[A] = ev /** - * Convert an implicit `PartialOrder[B]` to an `PartialOrder[A]` using the given - * function `f`. + * Convert an implicit `PartialOrder[B]` to an `PartialOrder[A]` using the given function `f`. */ def by[@sp A, @sp B](f: A => B)(implicit ev: PartialOrder[B]): PartialOrder[A] = (x, y) => ev.partialCompare(f(x), f(y)) diff --git a/kernel/src/main/scala/cats/kernel/Semigroup.scala b/kernel/src/main/scala/cats/kernel/Semigroup.scala index 561eb0e91c..3b52d69391 100644 --- a/kernel/src/main/scala/cats/kernel/Semigroup.scala +++ b/kernel/src/main/scala/cats/kernel/Semigroup.scala @@ -104,8 +104,7 @@ trait Semigroup[@sp(Int, Long, Float, Double) A] extends Any with Serializable { as.reduceOption(combine) /** - * return a semigroup that reverses the order - * so combine(a, b) == reverse.combine(b, a) + * return a semigroup that reverses the order so combine(a, b) == reverse.combine(b, a) */ def reverse: Semigroup[A] = new Semigroup[A] { @@ -116,8 +115,8 @@ trait Semigroup[@sp(Int, Long, Float, Double) A] extends Any with Serializable { } /** - * Between each pair of elements insert middle - * This name matches the term used in Foldable and Reducible and a similar Haskell function. + * Between each pair of elements insert middle This name matches the term used in Foldable and Reducible and a similar + * Haskell function. */ def intercalate(middle: A): Semigroup[A] = (a, b) => self.combine(a, self.combine(middle, b)) @@ -282,12 +281,13 @@ private[kernel] trait MonoidInstances extends BandInstances { /** * @deprecated - * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone - * (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). - * We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]]. - * However, at this time there are no plans to remove these instances from Cats. + * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone (particularly the semantics of + * [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). We recommend using + * [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of + * [[scala.concurrent.Future Future]]. However, at this time there are no plans to remove these instances from Cats. * - * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] + * @see + * [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] */ implicit def catsKernelMonoidForFuture[A](implicit A: Monoid[A], ec: ExecutionContext): Monoid[Future[A]] = new FutureMonoid[A](A, ec) @@ -324,11 +324,13 @@ private[kernel] trait SemigroupInstances { /** * @deprecated - * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone - * (particularly the semantics of [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). - * We recommend using [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of [[scala.concurrent.Future Future]]. + * Any non-pure use of [[scala.concurrent.Future Future]] with Cats is error prone (particularly the semantics of + * [[cats.Traverse#traverse traverse]] with regard to execution order are unspecified). We recommend using + * [[https://typelevel.org/cats-effect/ Cats Effect `IO`]] as a replacement for ''every'' use case of + * [[scala.concurrent.Future Future]]. * - * @see [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] + * @see + * [[https://github.com/typelevel/cats/issues/4176 Changes in Future traverse behavior between 2.6 and 2.7]] */ implicit def catsKernelSemigroupForFuture[A](implicit A: Semigroup[A], ec: ExecutionContext): Semigroup[Future[A]] = new FutureSemigroup[A](A, ec) diff --git a/kernel/src/main/scala/cats/kernel/Semilattice.scala b/kernel/src/main/scala/cats/kernel/Semilattice.scala index f3357e969a..872e33c214 100644 --- a/kernel/src/main/scala/cats/kernel/Semilattice.scala +++ b/kernel/src/main/scala/cats/kernel/Semilattice.scala @@ -24,22 +24,20 @@ package cats.kernel import scala.{specialized => sp} /** - * Semilattices are commutative semigroups whose operation - * (i.e. combine) is also idempotent. + * Semilattices are commutative semigroups whose operation (i.e. combine) is also idempotent. */ trait Semilattice[@sp(Int, Long, Float, Double) A] extends Any with Band[A] with CommutativeSemigroup[A] { self => /** - * Given Eq[A], return a PartialOrder[A] using the `combine` - * operator to determine the partial ordering. This method assumes - * `combine` functions as `meet` (that is, as a lower bound). + * Given Eq[A], return a PartialOrder[A] using the `combine` operator to determine the partial ordering. This method + * assumes `combine` functions as `meet` (that is, as a lower bound). * * This method returns: * - * 0.0 if x = y - * -1.0 if x = combine(x, y) - * 1.0 if y = combine(x, y) - * NaN otherwise + * - 0.0 if x = y + * - -1.0 if x = combine(x, y) + * - 1.0 if y = combine(x, y) + * - NaN otherwise */ def asMeetPartialOrder(implicit ev: Eq[A]): PartialOrder[A] = (x, y) => if (ev.eqv(x, y)) 0.0 @@ -49,16 +47,15 @@ trait Semilattice[@sp(Int, Long, Float, Double) A] extends Any with Band[A] with } /** - * Given Eq[A], return a PartialOrder[A] using the `combine` - * operator to determine the partial ordering. This method assumes - * `combine` functions as `join` (that is, as an upper bound). + * Given Eq[A], return a PartialOrder[A] using the `combine` operator to determine the partial ordering. This method + * assumes `combine` functions as `join` (that is, as an upper bound). * * This method returns: * - * 0.0 if x = y - * -1.0 if y = combine(x, y) - * 1.0 if x = combine(x, y) - * NaN otherwise + * - 0.0 if x = y + * - -1.0 if y = combine(x, y) + * - 1.0 if x = combine(x, y) + * - NaN otherwise */ def asJoinPartialOrder(implicit ev: Eq[A]): PartialOrder[A] = (x, y) => if (ev.eqv(x, y)) 0.0 diff --git a/kernel/src/main/scala/cats/kernel/instances/BigDecimalInstances.scala b/kernel/src/main/scala/cats/kernel/instances/BigDecimalInstances.scala index 2e430423b1..db28941794 100644 --- a/kernel/src/main/scala/cats/kernel/instances/BigDecimalInstances.scala +++ b/kernel/src/main/scala/cats/kernel/instances/BigDecimalInstances.scala @@ -30,12 +30,10 @@ trait BigDecimalInstances { } /** - * Note that combining, removing, and inverting `BigDecimal` values will use unlimited precision - * operations. + * Note that combining, removing, and inverting `BigDecimal` values will use unlimited precision operations. * - * This matches the behavior of Scala 2.12 and earlier versions, but not Scala 2.13, which means - * that `+` and `|+|` (or `sum` and `combineAll`) may not agree if you are working with values with - * limited-precision `MathContext`s. + * This matches the behavior of Scala 2.12 and earlier versions, but not Scala 2.13, which means that `+` and `|+|` (or + * `sum` and `combineAll`) may not agree if you are working with values with limited-precision `MathContext`s. */ class BigDecimalGroup extends CommutativeGroup[BigDecimal] { val empty: BigDecimal = BigDecimal(0) diff --git a/kernel/src/main/scala/cats/kernel/instances/DurationInstances.scala b/kernel/src/main/scala/cats/kernel/instances/DurationInstances.scala index 22314757d7..a2be602545 100644 --- a/kernel/src/main/scala/cats/kernel/instances/DurationInstances.scala +++ b/kernel/src/main/scala/cats/kernel/instances/DurationInstances.scala @@ -40,8 +40,7 @@ trait DurationBounded extends LowerBounded[Duration] with UpperBounded[Duration] /** * This ordering is valid for all defined durations. * - * The value Duration.Undefined breaks our laws, because undefined - * values are not equal to themselves. + * The value Duration.Undefined breaks our laws, because undefined values are not equal to themselves. */ class DurationOrder extends Order[Duration] with Hash[Duration] with DurationBounded { self => def hash(x: Duration): Int = x.hashCode() diff --git a/kernel/src/main/scala/cats/kernel/instances/FloatInstances.scala b/kernel/src/main/scala/cats/kernel/instances/FloatInstances.scala index 42b0838694..41d4818935 100644 --- a/kernel/src/main/scala/cats/kernel/instances/FloatInstances.scala +++ b/kernel/src/main/scala/cats/kernel/instances/FloatInstances.scala @@ -38,12 +38,11 @@ class FloatGroup extends CommutativeGroup[Float] { } /** - * Due to the way floating-point equality works, this instance is not - * lawful under equality, but is correct when taken as an - * approximation of an exact value. + * Due to the way floating-point equality works, this instance is not lawful under equality, but is correct when taken + * as an approximation of an exact value. * - * If you would prefer an absolutely lawful fractional value, you'll - * need to investigate rational numbers or more exotic types. + * If you would prefer an absolutely lawful fractional value, you'll need to investigate rational numbers or more exotic + * types. */ class FloatOrder extends Order[Float] with Hash[Float] { diff --git a/kernel/src/main/scala/cats/kernel/instances/StaticMethods.scala b/kernel/src/main/scala/cats/kernel/instances/StaticMethods.scala index 920eca9f09..35d97aa07a 100644 --- a/kernel/src/main/scala/cats/kernel/instances/StaticMethods.scala +++ b/kernel/src/main/scala/cats/kernel/instances/StaticMethods.scala @@ -61,8 +61,7 @@ object StaticMethods extends cats.kernel.compat.HashCompat { } /** - * When you "own" this m, and will not mutate it again, this - * is safe to call. It is unsafe to call this, then mutate + * When you "own" this m, and will not mutate it again, this is safe to call. It is unsafe to call this, then mutate * the original collection. * * You are giving up ownership when calling this method diff --git a/laws/src/main/scala/cats/laws/ApplicativeLaws.scala b/laws/src/main/scala/cats/laws/ApplicativeLaws.scala index c8e44453c2..de4223f3b5 100644 --- a/laws/src/main/scala/cats/laws/ApplicativeLaws.scala +++ b/laws/src/main/scala/cats/laws/ApplicativeLaws.scala @@ -44,9 +44,8 @@ trait ApplicativeLaws[F[_]] extends ApplyLaws[F] { fa.map(f) <-> F.pure(f).ap(fa) /** - * This law is [[applyComposition]] stated in terms of `pure`. It is a - * combination of [[applyComposition]] and [[applicativeMap]] and hence not - * strictly necessary. + * This law is [[applyComposition]] stated in terms of `pure`. It is a combination of [[applyComposition]] and + * [[applicativeMap]] and hence not strictly necessary. */ def applicativeComposition[A, B, C](fa: F[A], fab: F[A => B], fbc: F[B => C]): IsEq[F[C]] = { val compose: (B => C) => (A => B) => (A => C) = _.compose diff --git a/laws/src/main/scala/cats/laws/BimonadLaws.scala b/laws/src/main/scala/cats/laws/BimonadLaws.scala index aab44a7dba..addce12c01 100644 --- a/laws/src/main/scala/cats/laws/BimonadLaws.scala +++ b/laws/src/main/scala/cats/laws/BimonadLaws.scala @@ -25,8 +25,7 @@ package laws /** * Laws that must be obeyed by any `Bimonad`. * - * For more information, see definition 4.1 from this paper: - * http://arxiv.org/pdf/0710.1163v3.pdf + * For more information, see definition 4.1 from this paper: http://arxiv.org/pdf/0710.1163v3.pdf */ trait BimonadLaws[F[_]] extends MonadLaws[F] with ComonadLaws[F] { implicit override def F: Bimonad[F] diff --git a/laws/src/main/scala/cats/laws/CoflatMapLaws.scala b/laws/src/main/scala/cats/laws/CoflatMapLaws.scala index d71053c8ea..71b3476d0b 100644 --- a/laws/src/main/scala/cats/laws/CoflatMapLaws.scala +++ b/laws/src/main/scala/cats/laws/CoflatMapLaws.scala @@ -44,8 +44,7 @@ trait CoflatMapLaws[F[_]] extends FunctorLaws[F] { fa.coflatten <-> fa.coflatMap(identity) /** - * The composition of `cats.data.Cokleisli` arrows is associative. This is - * analogous to [[coflatMapAssociativity]]. + * The composition of `cats.data.Cokleisli` arrows is associative. This is analogous to [[coflatMapAssociativity]]. */ def cokleisliAssociativity[A, B, C, D](f: F[A] => B, g: F[B] => C, h: F[C] => D, fa: F[A]): IsEq[D] = { val (cf, cg, ch) = (Cokleisli(f), Cokleisli(g), Cokleisli(h)) diff --git a/laws/src/main/scala/cats/laws/CommutativeArrowLaws.scala b/laws/src/main/scala/cats/laws/CommutativeArrowLaws.scala index 73bf230e97..072646c525 100644 --- a/laws/src/main/scala/cats/laws/CommutativeArrowLaws.scala +++ b/laws/src/main/scala/cats/laws/CommutativeArrowLaws.scala @@ -27,8 +27,7 @@ import cats.syntax.compose.* import cats.syntax.strong.* /** - * Reference: "Causal Commutative Arrows", Journal of Functional Programming - * Figure 4. + * Reference: "Causal Commutative Arrows", Journal of Functional Programming Figure 4. */ trait CommutativeArrowLaws[F[_, _]] extends ArrowLaws[F] { implicit override def F: CommutativeArrow[F] diff --git a/laws/src/main/scala/cats/laws/ComonadLaws.scala b/laws/src/main/scala/cats/laws/ComonadLaws.scala index d7823624f0..cedf101d0e 100644 --- a/laws/src/main/scala/cats/laws/ComonadLaws.scala +++ b/laws/src/main/scala/cats/laws/ComonadLaws.scala @@ -47,15 +47,15 @@ trait ComonadLaws[F[_]] extends CoflatMapLaws[F] { fa.coflatMap(f).extract <-> f(fa) /** - * `extract` is the left identity element under left-to-right composition of - * `cats.data.Cokleisli` arrows. This is analogous to [[comonadLeftIdentity]]. + * `extract` is the left identity element under left-to-right composition of `cats.data.Cokleisli` arrows. This is + * analogous to [[comonadLeftIdentity]]. */ def cokleisliLeftIdentity[A, B](fa: F[A], f: F[A] => B): IsEq[B] = Cokleisli(F.extract[A]).andThen(Cokleisli(f)).run(fa) <-> f(fa) /** - * `extract` is the right identity element under left-to-right composition of - * `cats.data.Cokleisli` arrows. This is analogous to [[comonadRightIdentity]]. + * `extract` is the right identity element under left-to-right composition of `cats.data.Cokleisli` arrows. This is + * analogous to [[comonadRightIdentity]]. */ def cokleisliRightIdentity[A, B](fa: F[A], f: F[A] => B): IsEq[B] = Cokleisli(f).andThen(Cokleisli(F.extract[B])).run(fa) <-> f(fa) diff --git a/laws/src/main/scala/cats/laws/FlatMapLaws.scala b/laws/src/main/scala/cats/laws/FlatMapLaws.scala index 482ec6b430..1d2aa8e856 100644 --- a/laws/src/main/scala/cats/laws/FlatMapLaws.scala +++ b/laws/src/main/scala/cats/laws/FlatMapLaws.scala @@ -40,8 +40,7 @@ trait FlatMapLaws[F[_]] extends ApplyLaws[F] { fab.ap(fa) <-> fab.flatMap(f => fa.map(f)) /** - * The composition of `cats.data.Kleisli` arrows is associative. This is - * analogous to [[flatMapAssociativity]]. + * The composition of `cats.data.Kleisli` arrows is associative. This is analogous to [[flatMapAssociativity]]. */ def kleisliAssociativity[A, B, C, D](f: A => F[B], g: B => F[C], h: C => F[D], a: A): IsEq[F[D]] = { val (kf, kg, kh) = (Kleisli(f), Kleisli(g), Kleisli(h)) @@ -68,8 +67,7 @@ trait FlatMapLaws[F[_]] extends ApplyLaws[F] { } /** - * It is possible to implement flatMap from tailRecM and map - * and it should agree with the flatMap implementation. + * It is possible to implement flatMap from tailRecM and map and it should agree with the flatMap implementation. */ def flatMapFromTailRecMConsistency[A, B](fa: F[A], fn: A => F[B]): IsEq[F[B]] = { val tailRecMFlatMap = F.tailRecM[Option[A], B](Option.empty[A]) { diff --git a/laws/src/main/scala/cats/laws/MonadLaws.scala b/laws/src/main/scala/cats/laws/MonadLaws.scala index db071a559d..5dda25adb2 100644 --- a/laws/src/main/scala/cats/laws/MonadLaws.scala +++ b/laws/src/main/scala/cats/laws/MonadLaws.scala @@ -38,15 +38,15 @@ trait MonadLaws[F[_]] extends ApplicativeLaws[F] with FlatMapLaws[F] { fa.flatMap(F.pure) <-> fa /** - * `pure` is the left identity element under left-to-right composition of - * `cats.data.Kleisli` arrows. This is analogous to [[monadLeftIdentity]]. + * `pure` is the left identity element under left-to-right composition of `cats.data.Kleisli` arrows. This is + * analogous to [[monadLeftIdentity]]. */ def kleisliLeftIdentity[A, B](a: A, f: A => F[B]): IsEq[F[B]] = Kleisli(F.pure[A]).andThen(Kleisli(f)).run(a) <-> f(a) /** - * `pure` is the right identity element under left-to-right composition of - * `cats.data.Kleisli` arrows. This is analogous to [[monadRightIdentity]]. + * `pure` is the right identity element under left-to-right composition of `cats.data.Kleisli` arrows. This is + * analogous to [[monadRightIdentity]]. */ def kleisliRightIdentity[A, B](a: A, f: A => F[B]): IsEq[F[B]] = Kleisli(f).andThen(Kleisli(F.pure[B])).run(a) <-> f(a) diff --git a/laws/src/main/scala/cats/laws/StrongLaws.scala b/laws/src/main/scala/cats/laws/StrongLaws.scala index 4f2d37dfc0..274f82d0b2 100644 --- a/laws/src/main/scala/cats/laws/StrongLaws.scala +++ b/laws/src/main/scala/cats/laws/StrongLaws.scala @@ -29,8 +29,10 @@ import cats.syntax.strong.* /** * Laws that must be obeyed by any `cats.functor.Strong`. * - * See: [[https://arxiv.org/abs/1406.4823 E. Rivas, M. Jaskelioff Notions of Computation as Monoids, Chapter 7]] - * See: [[http://hackage.haskell.org/package/profunctors/docs/Data-Profunctor-Strong.html Haskell Data.Profunctor.Strong]] + * @see + * [[https://arxiv.org/abs/1406.4823 E. Rivas, M. Jaskelioff Notions of Computation as Monoids, Chapter 7]] + * @see + * [[http://hackage.haskell.org/package/profunctors/docs/Data-Profunctor-Strong.html Haskell Data.Profunctor.Strong]] */ trait StrongLaws[F[_, _]] extends ProfunctorLaws[F] { implicit override def F: Strong[F] @@ -81,16 +83,16 @@ trait StrongLaws[F[_, _]] extends ProfunctorLaws[F] { /** * first' . first' == dimap assoc unassoc . first' where - * assoc ((a,b),c) = (a,(b,c)) - * unassoc (a,(b,c)) = ((a,b),c) + * - assoc ((a,b),c) = (a,(b,c)) + * - unassoc (a,(b,c)) = ((a,b),c) */ def firstFirstIsDimap[A, B, C, D](fab: F[A, B]): IsEq[F[((A, C), D), ((B, C), D)]] = fab.first[C].first[D] <-> fab.first[(C, D)].dimap[((A, C), D), ((B, C), D)](assoc)(unassoc) /** * second' . second' == dimap unassoc assoc . second' where - * assoc ((a,b),c) = (a,(b,c)) - * unassoc (a,(b,c)) = ((a,b),c) + * - assoc ((a,b),c) = (a,(b,c)) + * - unassoc (a,(b,c)) = ((a,b),c) */ def secondSecondIsDimap[A, B, C, D](fab: F[A, B]): IsEq[F[(D, (C, A)), (D, (C, B))]] = fab.second[C].second[D] <-> fab.second[(D, C)].dimap[(D, (C, A)), (D, (C, B))](unassoc)(assoc) diff --git a/laws/src/main/scala/cats/laws/discipline/Eq.scala b/laws/src/main/scala/cats/laws/discipline/Eq.scala index 6e7e0a1d60..04dfc89c4f 100644 --- a/laws/src/main/scala/cats/laws/discipline/Eq.scala +++ b/laws/src/main/scala/cats/laws/discipline/Eq.scala @@ -141,8 +141,8 @@ object eq { ) object DeprecatedEqInstances { /** - * Create an approximation of Eq[A => B] by generating random values for A - * and comparing the application of the two functions. + * Create an approximation of Eq[A => B] by generating random values for A and comparing the application of the two + * functions. */ @deprecated( "This instance is problematic and will most likely be removed in a future version of Cats. Use catsLawsEqForFn1Exhaustive instead. See https://github.com/typelevel/cats/pull/2577 for more information.", @@ -158,8 +158,8 @@ object eq { } /** - * Create an approximation of Eq[(A, B) => C] by generating random values for A and B - * and comparing the application of the two functions. + * Create an approximation of Eq[(A, B) => C] by generating random values for A and B and comparing the application of + * the two functions. */ implicit def catsLawsEqForFn2[A, B, C](implicit A: Arbitrary[A], B: Arbitrary[B], C: Eq[C]): Eq[(A, B) => C] = Eq.by(_.tupled) @@ -177,8 +177,8 @@ object eq { Eq.by(showA => showA.show _) /** - * Create an approximate Eq instance for some type A, by comparing - * the behavior of `f(x, b)` and `f(y, b)` across many `b` samples. + * Create an approximate Eq instance for some type A, by comparing the behavior of `f(x, b)` and `f(y, b)` across many + * `b` samples. */ def sampledEq[A, B: Arbitrary, C: Eq](samples: Int)(f: (A, B) => C): Eq[A] = { val gen = Arbitrary.arbitrary[B] @@ -215,8 +215,8 @@ object eq { sampledEq[Ordering[A], (A, A), Int](100) { case (p, (l, r)) => p.compare(l, r) } /** - * Creates an approximation of `Eq[Hash[A]]` by generating 100 values for A - * and comparing the application of the two hash functions. + * Creates an approximation of `Eq[Hash[A]]` by generating 100 values for A and comparing the application of the two + * hash functions. */ implicit def catsLawsEqForHash[A](implicit arbA: Arbitrary[A]): Eq[Hash[A]] = { (f, g) => val samples = List.fill(100)(arbA.arbitrary.sample).collect { @@ -227,8 +227,8 @@ object eq { } /** - * Create an approximation of `Eq[Semigroup[A]]` by generating values for A - * and comparing the application of the two combine functions. + * Create an approximation of `Eq[Semigroup[A]]` by generating values for A and comparing the application of the two + * combine functions. */ implicit def catsLawsEqForSemigroup[A](implicit arbAA: Arbitrary[(A, A)], eqA: Eq[A]): Eq[Semigroup[A]] = Eq.by[Semigroup[A], ((A, A)) => A](f => { case (x, y) => f.combine(x, y) }) diff --git a/laws/src/main/scala/cats/laws/discipline/ExhaustiveCheck.scala b/laws/src/main/scala/cats/laws/discipline/ExhaustiveCheck.scala index 3ec2d4f7dd..9e2c81ee97 100644 --- a/laws/src/main/scala/cats/laws/discipline/ExhaustiveCheck.scala +++ b/laws/src/main/scala/cats/laws/discipline/ExhaustiveCheck.scala @@ -24,9 +24,8 @@ package laws package discipline /** - * An `ExhuastiveCheck[A]` instance can be used similarly to a ScalaCheck - * `Gen[A]` instance, but differs in that it generates a `List` of the entire - * domain of values as opposed to generating a random sampling of values. + * An `ExhuastiveCheck[A]` instance can be used similarly to a ScalaCheck `Gen[A]` instance, but differs in that it + * generates a `List` of the entire domain of values as opposed to generating a random sampling of values. */ trait ExhaustiveCheck[A] extends Serializable { self => def allValues: List[A] @@ -81,9 +80,9 @@ object ExhaustiveCheck { instance(None :: A.allValues.map(Some(_))) /** - * Creates an `ExhaustiveCheck[Set[A]]` given an `ExhaustiveCheck[A]` by computing the powerset of - * values. Note that if there are `n` elements in the domain of `A` there will be `2^n` elements - * in the domain of `Set[A]`, so use this only on small domains. + * Creates an `ExhaustiveCheck[Set[A]]` given an `ExhaustiveCheck[A]` by computing the powerset of values. Note that + * if there are `n` elements in the domain of `A` there will be `2^n` elements in the domain of `Set[A]`, so use this + * only on small domains. */ def forSet[A](implicit A: ExhaustiveCheck[A]): ExhaustiveCheck[Set[A]] = instance(A.allValues.toSet.subsets().toList) diff --git a/project/AlgebraBoilerplate.scala b/project/AlgebraBoilerplate.scala index 4e90334e8e..8e48aa700f 100644 --- a/project/AlgebraBoilerplate.scala +++ b/project/AlgebraBoilerplate.scala @@ -6,8 +6,10 @@ import sbt.* * Copied, with some modifications, from * [[https://github.com/milessabin/shapeless/blob/master/project/Boilerplate.scala Shapeless]]. * - * @author Miles Sabin - * @author Kevin Wright + * @author + * Miles Sabin + * @author + * Kevin Wright */ object AlgebraBoilerplate { import scala.StringContext.* @@ -49,17 +51,15 @@ object AlgebraBoilerplate { } /** - * Blocks in the templates below use a custom interpolator, combined with post-processing to - * produce the body. + * Blocks in the templates below use a custom interpolator, combined with post-processing to produce the body. * - * - The contents of the `header` val is output first - * - Then the first block of lines beginning with '|' - * - Then the block of lines beginning with '-' is replicated once for each arity, - * with the `templateVals` already pre-populated with relevant relevant vals for that arity - * - Then the last block of lines prefixed with '|' + * - The contents of the `header` val is output first + * - Then the first block of lines beginning with '|' + * - Then the block of lines beginning with '-' is replicated once for each arity, with the `templateVals` already + * pre-populated with relevant relevant vals for that arity + * - Then the last block of lines prefixed with '|' * - * The block otherwise behaves as a standard interpolated string with regards to variable - * substitution. + * The block otherwise behaves as a standard interpolated string with regards to variable substitution. */ trait Template { def filename(root: File): File diff --git a/project/Boilerplate.scala b/project/Boilerplate.scala index 741430ca03..d67dc5075f 100644 --- a/project/Boilerplate.scala +++ b/project/Boilerplate.scala @@ -5,11 +5,13 @@ import scala.annotation.tailrec /** * Copied, with some modifications, from https://github.com/milessabin/shapeless/blob/master/project/Boilerplate.scala * - * Generate a range of boilerplate classes, those offering alternatives with 0-22 params - * and would be tedious to craft by hand + * Generate a range of boilerplate classes, those offering alternatives with 0-22 params and would be tedious to craft + * by hand * - * @author Miles Sabin - * @author Kevin Wright + * @author + * Miles Sabin + * @author + * Kevin Wright */ object Boilerplate { import scala.StringContext.* @@ -44,7 +46,7 @@ object Boilerplate { val header = "// auto-generated boilerplate by /project/Boilerplate.scala" // TODO: put something meaningful here? /** - * Returns a seq of the generated files. As a side-effect, it actually generates them... + * Returns a seq of the generated files. As a side-effect, it actually generates them... */ def gen(dir: File) = for (t <- templates) yield { diff --git a/project/KernelBoiler.scala b/project/KernelBoiler.scala index f0c28b69aa..a59f4b0add 100644 --- a/project/KernelBoiler.scala +++ b/project/KernelBoiler.scala @@ -6,8 +6,10 @@ import sbt.* * Copied, with some modifications, from * [[https://github.com/milessabin/shapeless/blob/master/project/Boilerplate.scala Shapeless]]. * - * @author Miles Sabin - * @author Kevin Wright + * @author + * Miles Sabin + * @author + * Kevin Wright */ object KernelBoiler { import scala.StringContext.* @@ -50,17 +52,15 @@ object KernelBoiler { } /** - * Blocks in the templates below use a custom interpolator, combined with post-processing to - * produce the body. + * Blocks in the templates below use a custom interpolator, combined with post-processing to produce the body. * - * - The contents of the `header` val is output first - * - Then the first block of lines beginning with '|' - * - Then the block of lines beginning with '-' is replicated once for each arity, - * with the `templateVals` already pre-populated with relevant relevant vals for that arity - * - Then the last block of lines prefixed with '|' + * - The contents of the `header` val is output first + * - Then the first block of lines beginning with '|' + * - Then the block of lines beginning with '-' is replicated once for each arity, with the `templateVals` already + * pre-populated with relevant relevant vals for that arity + * - Then the last block of lines prefixed with '|' * - * The block otherwise behaves as a standard interpolated string with regards to variable - * substitution. + * The block otherwise behaves as a standard interpolated string with regards to variable substitution. */ trait Template { def filename(root: File): File diff --git a/project/TupleMonadInstancesBoiler.scala b/project/TupleMonadInstancesBoiler.scala index 61a4bf6288..0de5ef7874 100644 --- a/project/TupleMonadInstancesBoiler.scala +++ b/project/TupleMonadInstancesBoiler.scala @@ -16,10 +16,8 @@ object GenTupleMonadInstances extends Template { val `b:A..(n - 1):(N - 1)` = (for ((v, t) <- `b..(n - 1)`.zip(`A..(N - 1)`)) yield s"$v: $t").mkString(", ") /** - * This special case for N = 2 is needed because - * of the deprecated versions in TupleInstances. - * It will be removed once the deprecated ones are - * deleted. + * This special case for `N = 2` is needed because of the deprecated versions in `TupleInstances`. It will be + * removed once the deprecated ones are deleted. */ val flatMapTupleClass = if (arity == 2) "FlatMapNTuple2" else s"FlatMapTuple$arity" diff --git a/testkit/src/main/scala/cats/tests/Helpers.scala b/testkit/src/main/scala/cats/tests/Helpers.scala index 70a5c94f59..52024082c6 100644 --- a/testkit/src/main/scala/cats/tests/Helpers.scala +++ b/testkit/src/main/scala/cats/tests/Helpers.scala @@ -26,18 +26,17 @@ import org.scalacheck.{Arbitrary, Cogen} import org.scalacheck.Arbitrary.arbitrary /** - * Helpers provides new concrete types where we control exactly which - * type class instances are available. For example, the SL type has: + * Helpers provides new concrete types where we control exactly which type class instances are available. For example, + * the SL type has: * - * - Semilattice[SL] - * - Arbitrary[SL] - * - Eq[SL] + * - Semilattice[SL] + * - Arbitrary[SL] + * - Eq[SL] * * (All types in Helpers have Arbitrary and Eq instances.) * - * These are useful when a type constructor (e.g. Function0) can - * produce many different instances depending on which instances are - * available for its type parameter. + * These are useful when a type constructor (e.g. Function0) can produce many different instances depending on which + * instances are available for its type parameter. */ object Helpers { diff --git a/testkit/src/main/scala/cats/tests/ListWrapper.scala b/testkit/src/main/scala/cats/tests/ListWrapper.scala index be2303624f..03a0a3ebd0 100644 --- a/testkit/src/main/scala/cats/tests/ListWrapper.scala +++ b/testkit/src/main/scala/cats/tests/ListWrapper.scala @@ -28,23 +28,18 @@ import org.scalacheck.Arbitrary.arbitrary /** * This data type exists purely for testing. * - * The problem this type solves is to assist in picking up type class - * instances that have more general constraints. + * The problem this type solves is to assist in picking up type class instances that have more general constraints. * - * For instance, OneAnd[*, F[_]] has a Monad instance if F[_] does too. - * By extension, it has an Applicative instance, since Applicative is - * a superclass of Monad. + * For instance, OneAnd[*, F[_]] has a Monad instance if F[_] does too. By extension, it has an Applicative instance, + * since Applicative is a superclass of Monad. * - * However, if F[_] doesn't have a Monad instance but does have an - * Applicative instance (e.g. Validated), you can still get an - * Applicative instance for OneAnd[*, F[_]]. These two instances - * are different however, and it is a good idea to test to make sure - * all "variants" of the instances are lawful. + * However, if F[_] doesn't have a Monad instance but does have an Applicative instance (e.g. Validated), you can still + * get an Applicative instance for OneAnd[*, F[_]]. These two instances are different however, and it is a good idea to + * test to make sure all "variants" of the instances are lawful. * - * By providing this data type, we can have implicit search pick up - * a specific type class instance by asking for it explicitly in a block. - * Note that ListWrapper has no type class instances in implicit scope, - * save for ones related to testing (e.g. Eq, Arbitrary, Cogen). + * By providing this data type, we can have implicit search pick up a specific type class instance by asking for it + * explicitly in a block. Note that ListWrapper has no type class instances in implicit scope, save for ones related to + * testing (e.g. Eq, Arbitrary, Cogen). * * {{{ * { diff --git a/tests/shared/src/test/scala/cats/tests/BinCodecInvariantMonoidalSuite.scala b/tests/shared/src/test/scala/cats/tests/BinCodecInvariantMonoidalSuite.scala index 76bce46095..af84b8715d 100644 --- a/tests/shared/src/test/scala/cats/tests/BinCodecInvariantMonoidalSuite.scala +++ b/tests/shared/src/test/scala/cats/tests/BinCodecInvariantMonoidalSuite.scala @@ -88,9 +88,8 @@ object BinCodecInvariantMonoidalSuite { /** * Type class to read and write objects of type A to binary. * - * Obeys `forAll { (c: BinCodec[A], a: A) => c.read(c.writes(a)) == (Some(a), List())`, - * under the assumtion that `imap(f, g)` is always called with `f` and `g` such that - * `forAll { (a: A) => g(f(a)) == a }`. + * Obeys `forAll { (c: BinCodec[A], a: A) => c.read(c.writes(a)) == (Some(a), List())`, under the assumtion that + * `imap(f, g)` is always called with `f` and `g` such that `forAll { (a: A) => g(f(a)) == a }`. */ trait BinCodec[A] extends Serializable { self => diff --git a/tests/shared/src/test/scala/cats/tests/CatsSuite.scala b/tests/shared/src/test/scala/cats/tests/CatsSuite.scala index b90ecb6593..8ab9a4bffa 100644 --- a/tests/shared/src/test/scala/cats/tests/CatsSuite.scala +++ b/tests/shared/src/test/scala/cats/tests/CatsSuite.scala @@ -43,8 +43,7 @@ trait TestSettings { } /** - * An opinionated stack of traits to improve consistency and reduce - * boilerplate in Cats tests. + * An opinionated stack of traits to improve consistency and reduce boilerplate in Cats tests. */ trait CatsSuite extends munit.DisciplineSuite with TestSettings { diff --git a/tests/shared/src/test/scala/cats/tests/EvalSuite.scala b/tests/shared/src/test/scala/cats/tests/EvalSuite.scala index d41e0cda67..57525d10f7 100644 --- a/tests/shared/src/test/scala/cats/tests/EvalSuite.scala +++ b/tests/shared/src/test/scala/cats/tests/EvalSuite.scala @@ -45,20 +45,17 @@ class EvalSuite extends CatsSuite { implicit val eqThrow: Eq[Throwable] = Eq.allEqual /** - * This method creates a Eval[A] instance (along with a - * corresponding Spooky instance) from an initial `value` using the - * given `init` function. + * This method creates a Eval[A] instance (along with a corresponding Spooky instance) from an initial `value` using + * the given `init` function. * - * It will then proceed to call `value` 0-or-more times, verifying - * that the result is equal to `value`, and also that the - * appropriate number of evaluations are occurring using the - * `numCalls` function. + * It will then proceed to call `value` 0-or-more times, verifying that the result is equal to `value`, and also that + * the appropriate number of evaluations are occurring using the `numCalls` function. * * In other words, each invocation of run says: * - * 1. What underlying `value` to use. - * 2. How to create Eval instances (memoized, eager, or by-name). - * 3. How many times we expect the value to be computed. + * 1. What underlying `value` to use. + * 2. How to create Eval instances (memoized, eager, or by-name). + * 3. How many times we expect the value to be computed. */ def runValue[A: Eq](value: A)(init: A => (Spooky, Eval[A]))(numCalls: Int => Int): Unit = { var spin = 0 diff --git a/tests/shared/src/test/scala/cats/tests/PartialOrderSuite.scala b/tests/shared/src/test/scala/cats/tests/PartialOrderSuite.scala index 05a63a0b0e..2810436956 100644 --- a/tests/shared/src/test/scala/cats/tests/PartialOrderSuite.scala +++ b/tests/shared/src/test/scala/cats/tests/PartialOrderSuite.scala @@ -34,8 +34,8 @@ import org.scalacheck.Prop.* class PartialOrderSuite extends CatsSuite { /** - * Check that two partial compare results are "the same". - * This works around the fact that `NaN` is not equal to itself. + * Check that two partial compare results are "the same". This works around the fact that `NaN` is not equal to + * itself. */ def checkPartialCompare(res1: Double, res2: Double): Unit = assert(res1 == res2 || (res1.isNaN && res2.isNaN)) diff --git a/tests/shared/src/test/scala/cats/tests/Spooky.scala b/tests/shared/src/test/scala/cats/tests/Spooky.scala index 1c9ed6ace9..8c9978a359 100644 --- a/tests/shared/src/test/scala/cats/tests/Spooky.scala +++ b/tests/shared/src/test/scala/cats/tests/Spooky.scala @@ -24,8 +24,8 @@ package cats.tests /** * Class for spooky side-effects and action-at-a-distance. * - * It is basically a mutable counter that can be used to measure how - * many times an otherwise pure function is being evaluated. + * It is basically a mutable counter that can be used to measure how many times an otherwise pure function is being + * evaluated. */ class Spooky(var counter: Int = 0) { def increment(): Unit = counter += 1 diff --git a/tests/shared/src/test/scala/cats/tests/SyntaxSuite.scala b/tests/shared/src/test/scala/cats/tests/SyntaxSuite.scala index 3e18524138..0919b97403 100644 --- a/tests/shared/src/test/scala/cats/tests/SyntaxSuite.scala +++ b/tests/shared/src/test/scala/cats/tests/SyntaxSuite.scala @@ -46,18 +46,14 @@ import scala.collection.immutable.{SortedMap, SortedSet} /** * Test that our syntax implicits are working. * - * Each method should correspond to one type class worth of syntax. - * Ideally, we should be testing every operator or method that we - * expect to add to generic parameters. This file is a safeguard - * against accidentally breaking (or removing) syntax which was - * otherwise untested. + * Each method should correspond to one type class worth of syntax. Ideally, we should be testing every operator or + * method that we expect to add to generic parameters. This file is a safeguard against accidentally breaking (or + * removing) syntax which was otherwise untested. * - * The strategy here is to create "mock" values of particular types, - * and then ensure that the syntax we want is available. We never plan - * to run any of these methods, so we don't need real values. All - * values in the methods should be generic -- we rely on parametricity - * to guarantee that the syntax will be available for any type with - * the proper type class instance(s). + * The strategy here is to create "mock" values of particular types, and then ensure that the syntax we want is + * available. We never plan to run any of these methods, so we don't need real values. All values in the methods should + * be generic -- we rely on parametricity to guarantee that the syntax will be available for any type with the proper + * type class instance(s). * * None of these tests should ever run, or do any runtime checks. */