Merge pull request #1042 from som-snytt/format/doc-comments

Prefer docstrings.style = AsteriskSpace

.scalafmt.conf

@@ -11,6 +11,8 @@ danglingParentheses {
   callSite = false
 }
 
+docstrings.style = AsteriskSpace
+
 newlines {
   source = keep
 }

bench/src/main/scala/org/scalacheck/bench/GenBench.scala

@@ -17,30 +17,30 @@ import org.scalacheck.Gen
 import org.scalacheck.rng.Seed
 
 /** Generator benchmarks
-  *
-  * Since generators may run very quickly (or very slowly) depending on the seed and size parameter used, we want to
-  * make sure these are held constant across runs. Otherwise, we might believe a particular change made a given
-  * generator faster (or slower) when in fact we just got lucky (or unlucky).
-  *
-  * We use `seedCount` to choose how many seeds we will benchmark with. For each seed, we run the given generator. So if
-  * `seedCount` is 100, the average time we get is the time to generate values for the 100 seeds we started with.
-  *
-  * The size parameter also plays a major role in how long generators take. ScalaCheck's default parameters start with
-  * 100. You can benchmark additional size parameters to see how changes to this parameter effect generator run time.
-  *
-  * Finally, a generator's `apply` method may fail to generate a value. This might allow a slow generator that fails 50%
-  * of the time to appear faster than other generators that don't fail. Since we expect all generators to be able to
-  * succeed, we benchmark using `pureApply`, which will retry up to 100 times before crashing. This way, there's no
-  * chance that a flaky generator gets an advantage during benchmarking.
-  *
-  * In theory, we should do as much work as possible outside the benchmark methods to avoid benchmarking construction
-  * time. However, since many generators are constructed inside of `flatMap` calls during generation we do want these
-  * constructors to also run as quickly as possible. For that reason, we mostly choose to assemble our generators inside
-  * the benchmark methods.
-  *
-  * Prefer to add new benchmarks instead of modifying existing ones. This will enable us to compare the results for a
-  * given benchmark over time.
-  */
+ *
+ *  Since generators may run very quickly (or very slowly) depending on the seed and size parameter used, we want to
+ *  make sure these are held constant across runs. Otherwise, we might believe a particular change made a given
+ *  generator faster (or slower) when in fact we just got lucky (or unlucky).
+ *
+ *  We use `seedCount` to choose how many seeds we will benchmark with. For each seed, we run the given generator. So if
+ *  `seedCount` is 100, the average time we get is the time to generate values for the 100 seeds we started with.
+ *
+ *  The size parameter also plays a major role in how long generators take. ScalaCheck's default parameters start with
+ *  100. You can benchmark additional size parameters to see how changes to this parameter effect generator run time.
+ *
+ *  Finally, a generator's `apply` method may fail to generate a value. This might allow a slow generator that fails 50%
+ *  of the time to appear faster than other generators that don't fail. Since we expect all generators to be able to
+ *  succeed, we benchmark using `pureApply`, which will retry up to 100 times before crashing. This way, there's no
+ *  chance that a flaky generator gets an advantage during benchmarking.
+ *
+ *  In theory, we should do as much work as possible outside the benchmark methods to avoid benchmarking construction
+ *  time. However, since many generators are constructed inside of `flatMap` calls during generation we do want these
+ *  constructors to also run as quickly as possible. For that reason, we mostly choose to assemble our generators inside
+ *  the benchmark methods.
+ *
+ *  Prefer to add new benchmarks instead of modifying existing ones. This will enable us to compare the results for a
+ *  given benchmark over time.
+ */
 @State(Scope.Benchmark)
 @BenchmarkMode(Array(Mode.AverageTime))
 @OutputTimeUnit(TimeUnit.MICROSECONDS)

core/jvm/src/test/scala/org/scalacheck/ChooseSpecification.scala

@@ -61,8 +61,8 @@ object ChooseSpecification extends Properties("Choose") with time.OrderingVersio
   property("choose[ZonedDateTime]") = chooseProp[ZonedDateTime]
 
   /** Generate a duration which is at least 1 second smaller than the max duration the type can support. We use this to
-    * avoid the incredibly unlikely event of overflowing in the handle-min-nanos-duration test.
-    */
+   *  avoid the incredibly unlikely event of overflowing in the handle-min-nanos-duration test.
+   */
   lazy val genOneSecondLessThanMaxDuration: Gen[Duration] =
     Gen.choose(Duration.ofSeconds(Long.MinValue), Duration.ofSeconds(Long.MaxValue - 1L, 999999999L))
 
@@ -80,8 +80,8 @@ object ChooseSpecification extends Properties("Choose") with time.OrderingVersio
     }
 
   /** Generate an Instant which is at least 1 second smaller than the max Instant the type can support. We use this to
-    * avoid the incredibly unlikely event of overflowing in the handle-min-nanos-instant test.
-    */
+   *  avoid the incredibly unlikely event of overflowing in the handle-min-nanos-instant test.
+   */
   lazy val genOneSecondLessThanMaxInstant: Gen[Instant] =
     Gen.choose(Instant.MIN, Instant.MAX.minusSeconds(1L))
 

core/jvm/src/test/scala/org/scalacheck/GenSpecification.scala

@@ -273,13 +273,13 @@ object GenSpecification extends Properties("Gen") with GenSpecificationVersionSp
   }
 
   /** Expect:
-    * {{{
-    * 25% 1, 2, 3
-    * 25% 1, 2, 4
-    * 25% 1, 4, 3
-    * 25% 4, 2, 3
-    * }}}
-    */
+   *  {{{
+   *  25% 1, 2, 3
+   *  25% 1, 2, 4
+   *  25% 1, 4, 3
+   *  25% 4, 2, 3
+   *  }}}
+   */
   property("distributed pick") = {
     val lst = (1 to 4).toIterable
     val n = 3
@@ -640,10 +640,10 @@ object GenSpecification extends Properties("Gen") with GenSpecificationVersionSp
   }
 
   /** Ensure that the given generator runs deterministically with the same initialSeed parameter or the same seed.
-    *
-    * This test should be run with a generator that can produce multiple values, and where the odds of 30 trials coming
-    * back with the same result is low enough that the test won't produce many false positives.
-    */
+   *
+   *  This test should be run with a generator that can produce multiple values, and where the odds of 30 trials coming
+   *  back with the same result is low enough that the test won't produce many false positives.
+   */
   def testDeterministicGen[A](g: Gen[A]): Prop = {
     val params0 = Gen.Parameters.default
     val params1 = params0.withInitialSeed(1248163264L)

core/jvm/src/test/scala/org/scalacheck/ShrinkSpecificationJVM.scala

@@ -14,8 +14,8 @@ import Shrink.shrink
 import ShrinkSpecification.shrinkClosure
 
 /** @todo
-  *   should work not only JVM but also Scala.js
-  */
+ *    should work not only JVM but also Scala.js
+ */
 object ShrinkSpecificationJVM extends Properties("Shrink JVM") {
 
   property("list") = forAll { (l: List[Int]) =>

core/shared/src/main/scala-2.12-/org/scalacheck/util/BuildableVersionSpecific.scala

@@ -33,7 +33,7 @@ private[util] class ArrayListBuilder[T] extends Builder[T, ArrayList[T]] {
 }
 
 /** CanBuildFrom instances implementing Serializable, so that the objects capturing those can be serializable too.
-  */
+ */
 object SerializableCanBuildFroms {
   implicit def listCanBuildFrom[T]: CanBuildFrom[List[T], T, List[T]] =
     new CanBuildFrom[List[T], T, List[T]] with Serializable {

core/shared/src/main/scala-2.13+/org/scalacheck/util/BuildableVersionSpecific.scala

@@ -31,7 +31,7 @@ private[util] class ArrayListBuilder[T] extends Builder[T, ArrayList[T]] {
 }
 
 /** Factory instances implementing Serializable, so that the objects capturing those can be serializable too.
-  */
+ */
 // Named `...CanBuildFroms` for 2.12 source compatibility (`import SerializableCanBuildFroms._`)
 // Can be renamed to `SerializableFactories` in a major release.
 object SerializableCanBuildFroms {

core/shared/src/main/scala/org/scalacheck/Arbitrary.scala

@@ -20,65 +20,65 @@ import util.Buildable
 import util.SerializableCanBuildFroms._
 
 /** Define an arbitrary generator for properties
-  *
-  * The [[Arbitrary]] module defines implicit generator instances for common types.
-  *
-  * The implicit definitions of [[Arbitrary]] provide type-directed [[Gen]]s so they are available for properties,
-  * generators, or other definitions of [[Arbitrary]].
-  *
-  * ScalaCheck expects an implicit [[Arbitrary]] instance is in scope for [[Prop]]s that are defined with functions,
-  * like [[Prop$.forAll[T1,P](g1* Prop.forAll]] and so on.
-  *
-  * For instance, the definition for `Arbitrary[Boolean]` is used by `Prop.forAll` to automatically provide a
-  * `Gen[Boolean]` when one of the parameters is a `Boolean`:
-  *
-  * {{{
-  *    Prop.forAll { (b: Boolean) =>
-  *      b || !b
-  *    }
-  * }}}
-  *
-  * Thanks to `Arbitrary`, you don't need to provide an explicit `Gen` instance to `Prop.forAll`. For instance, this is
-  * unnecessary:
-  *
-  * {{{
-  *    val genBool: Gen[Boolean] = Gen.oneOf(true,false)
-  *    Prop.forAll(genBool) { (b: Boolean) =>
-  *      b || !b
-  *    }
-  * }}}
-  *
-  * Since an arbitrary `Gen` for `Boolean` is defined in `Arbitrary`, it can be summoned with `Arbitrary.arbitrary` in
-  * cases where you need to provide one explicitly:
-  *
-  * {{{
-  *    val genBool: Gen[Boolean] = Arbitrary.arbitrary[Boolean]
-  *    val genSmallInt: Gen[Int] = Gen.choose(0, 9)
-  *    Prop.forAll(genBool, genSmallInt) { (b: Boolean, i: Int) =>
-  *      i < 10 && b || !b
-  *    }
-  * }}}
-  *
-  * For a user-defined `MyClass`, writing the following requires that there exists an implicit `Arbitrary[MyClass]`
-  * instance:
-  *
-  * {{{
-  *    Prop.forAll { (myClass: MyClass) =>
-  *      ...
-  *    }
-  * }}}
-  *
-  * The implicit definition of `Arbitrary[MyClass]` would look like:
-  *
-  * {{{
-  *    implicit val arbMyClass: Arbitrary[MyClass] = Arbitrary {
-  *      ...
-  *    }
-  * }}}
-  *
-  * The factory method `Arbitrary(...)` expects a generator of type `Gen[MyClass]` then it will return an instance of
-  * `Arbitrary[MyClass]`.
-  */
+ *
+ *  The [[Arbitrary]] module defines implicit generator instances for common types.
+ *
+ *  The implicit definitions of [[Arbitrary]] provide type-directed [[Gen]]s so they are available for properties,
+ *  generators, or other definitions of [[Arbitrary]].
+ *
+ *  ScalaCheck expects an implicit [[Arbitrary]] instance is in scope for [[Prop]]s that are defined with functions,
+ *  like [[Prop$.forAll[T1,P](g1* Prop.forAll]] and so on.
+ *
+ *  For instance, the definition for `Arbitrary[Boolean]` is used by `Prop.forAll` to automatically provide a
+ *  `Gen[Boolean]` when one of the parameters is a `Boolean`:
+ *
+ *  {{{
+ *    Prop.forAll { (b: Boolean) =>
+ *      b || !b
+ *    }
+ *  }}}
+ *
+ *  Thanks to `Arbitrary`, you don't need to provide an explicit `Gen` instance to `Prop.forAll`. For instance, this is
+ *  unnecessary:
+ *
+ *  {{{
+ *    val genBool: Gen[Boolean] = Gen.oneOf(true,false)
+ *    Prop.forAll(genBool) { (b: Boolean) =>
+ *      b || !b
+ *    }
+ *  }}}
+ *
+ *  Since an arbitrary `Gen` for `Boolean` is defined in `Arbitrary`, it can be summoned with `Arbitrary.arbitrary` in
+ *  cases where you need to provide one explicitly:
+ *
+ *  {{{
+ *    val genBool: Gen[Boolean] = Arbitrary.arbitrary[Boolean]
+ *    val genSmallInt: Gen[Int] = Gen.choose(0, 9)
+ *    Prop.forAll(genBool, genSmallInt) { (b: Boolean, i: Int) =>
+ *      i < 10 && b || !b
+ *    }
+ *  }}}
+ *
+ *  For a user-defined `MyClass`, writing the following requires that there exists an implicit `Arbitrary[MyClass]`
+ *  instance:
+ *
+ *  {{{
+ *    Prop.forAll { (myClass: MyClass) =>
+ *      ...
+ *    }
+ *  }}}
+ *
+ *  The implicit definition of `Arbitrary[MyClass]` would look like:
+ *
+ *  {{{
+ *    implicit val arbMyClass: Arbitrary[MyClass] = Arbitrary {
+ *      ...
+ *    }
+ *  }}}
+ *
+ *  The factory method `Arbitrary(...)` expects a generator of type `Gen[MyClass]` then it will return an instance of
+ *  `Arbitrary[MyClass]`.
+ */
 sealed abstract class Arbitrary[T] extends Serializable {
   def arbitrary: Gen[T]
 }
@@ -103,7 +103,7 @@ private[scalacheck] sealed trait ArbitraryLowPriority {
   def arbitrary[T](implicit a: Arbitrary[T]): Gen[T] = a.arbitrary
 
   /** ** Arbitrary instances for each AnyVal ***
-    */
+   */
 
   /** Arbitrary AnyVal */
   implicit lazy val arbAnyVal: Arbitrary[AnyVal] = Arbitrary(oneOf(
@@ -174,7 +174,7 @@ private[scalacheck] sealed trait ArbitraryLowPriority {
     Arbitrary(Gen.const(()))
 
   /** Arbitrary instances of other common types
-    */
+   */
 
   /** Arbitrary instance of String */
   implicit lazy val arbString: Arbitrary[String] =
@@ -307,10 +307,10 @@ private[scalacheck] sealed trait ArbitraryLowPriority {
     Arbitrary(Gen.finiteDuration)
 
   /** Arbitrary instance of Duration.
-    *
-    * In addition to `FiniteDuration` values, this can generate `Duration.Inf`, `Duration.MinusInf`, and
-    * `Duration.Undefined`.
-    */
+   *
+   *  In addition to `FiniteDuration` values, this can generate `Duration.Inf`, `Duration.MinusInf`, and
+   *  `Duration.Undefined`.
+   */
   implicit lazy val arbDuration: Arbitrary[Duration] =
     Arbitrary(Gen.duration)
 
@@ -385,17 +385,17 @@ private[scalacheck] sealed trait ArbitraryLowPriority {
     Arbitrary(Gen.oneOf(arbitrary[T].map(Success(_)), arbitrary[Throwable].map(Failure(_))))
 
   /** Arbitrary instance of any [[org.scalacheck.util.Buildable]] container (such as lists, arrays, streams / lazy
-    * lists, etc). The maximum size of the container depends on the size generation parameter.
-    */
+   *  lists, etc). The maximum size of the container depends on the size generation parameter.
+   */
   implicit def arbContainer[C[_], T](implicit
       a: Arbitrary[T],
       b: Buildable[T, C[T]],
       t: C[T] => Traversable[T]
   ): Arbitrary[C[T]] = Arbitrary(buildableOf[C[T], T](arbitrary[T]))
 
   /** Arbitrary instance of any [[org.scalacheck.util.Buildable]] container (such as maps). The maximum size of the
-    * container depends on the size generation parameter.
-    */
+   *  container depends on the size generation parameter.
+   */
   implicit def arbContainer2[C[_, _], T, U](implicit
       a: Arbitrary[(T, U)],
       b: Buildable[(T, U), C[T, U]],