Use ccoll and align margins

Author: som-snytt

library/src/scala/collection/Iterable.scala

@@ -127,7 +127,7 @@ trait Iterable[+A] extends IterableOnce[A]
   * @define willNotTerminateInf
   *
   *    Note: will not terminate for infinite-sized collections.
-  *  @define undefinedorder
+  * @define undefinedorder
   *  The order in which operations are performed on elements is unspecified
   *  and may be nondeterministic.
   */
@@ -140,9 +140,9 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
   def toIterable: Iterable[A]
 
   /** Converts this $coll to an unspecified Iterable.  Will return
-    *  the same collection if this instance is already Iterable.
-    *  @return An Iterable containing all elements of this $coll.
-    */
+   *  the same collection if this instance is already Iterable.
+   *  @return An Iterable containing all elements of this $coll.
+   */
   @deprecated("toTraversable is internal and will be made protected; its name is similar to `toList` or `toSeq`, but it doesn't copy non-immutable collections", "2.13.0")
   final def toTraversable: Traversable[A] = toIterable
 
@@ -208,24 +208,24 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
     */
   protected def newSpecificBuilder: Builder[A @uncheckedVariance, C]
 
-  /** The empty iterable of the same type as this iterable.
+  /** The empty $coll.
     *
-    * @return an empty iterable of type `C`.
+    * @return an empty iterable of type $Coll.
     */
   def empty: C = fromSpecific(Nil)
 
   /** Selects the first element of this $coll.
-    *  $orderDependent
-    *  @return  the first element of this $coll.
-    *  @throws NoSuchElementException if the $coll is empty.
-    */
+   *  $orderDependent
+   *  @return  the first element of this $coll.
+   *  @throws NoSuchElementException if the $coll is empty.
+   */
   def head: A = iterator.next()
 
   /** Optionally selects the first element.
-    *  $orderDependent
-    *  @return  the first element of this $coll if it is nonempty,
-    *           `None` if it is empty.
-    */
+   *  $orderDependent
+   *  @return  the first element of this $coll if it is nonempty,
+   *           `None` if it is empty.
+   */
   def headOption: Option[A] = {
     val it = iterator
     if (it.hasNext) Some(it.next()) else None
@@ -244,32 +244,32 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
   }
 
   /** Optionally selects the last element.
-    *  $orderDependent
-    *  @return  the last element of this $coll$ if it is nonempty,
-    *           `None` if it is empty.
-    */
+   *  $orderDependent
+   *  @return  the last element of this $coll if it is nonempty,
+   *           `None` if it is empty.
+   */
   def lastOption: Option[A] = if (isEmpty) None else Some(last)
 
   /** A view over the elements of this collection. */
   def view: View[A] = View.fromIteratorProvider(() => iterator)
 
   /** Compares the size of this $coll to a test value.
-    *
-    *   @param   otherSize the test value that gets compared with the size.
-    *   @return  A value `x` where
-    *   {{{
-    *        x <  0       if this.size <  otherSize
-    *        x == 0       if this.size == otherSize
-    *        x >  0       if this.size >  otherSize
-    *   }}}
-    *
-    *  The method as implemented here does not call `size` directly; its running time
-    *  is `O(size min otherSize)` instead of `O(size)`. The method should be overridden
-    *  if computing `size` is cheap and `knownSize` returns `-1`.
-    *
-    *  @see [[sizeIs]]
-    */
-  def sizeCompare(otherSize: Int): Int = {
+   *
+   *  @param   otherSize the test value that gets compared with the size.
+   *  @return  A value `x` where
+   *  {{{
+   *       x <  0       if this.size <  otherSize
+   *       x == 0       if this.size == otherSize
+   *       x >  0       if this.size >  otherSize
+   *  }}}
+   *
+   *  The method as implemented here does not call `size` directly; its running time
+   *  is `O(size min otherSize)` instead of `O(size)`. The method should be overridden
+   *  if computing `size` is cheap and `knownSize` returns `-1`.
+   *
+   *  @see [[sizeIs]]
+   */
+  def sizeCompare(otherSize: Int): Int =
     if (otherSize < 0) 1
     else {
       val known = knownSize
@@ -285,7 +285,6 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
         i - otherSize
       }
     }
-  }
 
   /** Returns a value class containing operations for comparing the size of this $coll to a test value.
     *
@@ -304,19 +303,19 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
   @inline final def sizeIs: IterableOps.SizeCompareOps = new IterableOps.SizeCompareOps(this)
 
   /** Compares the size of this $coll to the size of another `Iterable`.
-    *
-    *   @param   that the `Iterable` whose size is compared with this $coll's size.
-    *   @return  A value `x` where
-    *   {{{
-    *        x <  0       if this.size <  that.size
-    *        x == 0       if this.size == that.size
-    *        x >  0       if this.size >  that.size
-    *   }}}
-    *
-    *  The method as implemented here does not call `size` directly; its running time
-    *  is `O(this.size min that.size)` instead of `O(this.size + that.size)`.
-    *  The method should be overridden if computing `size` is cheap and `knownSize` returns `-1`.
-    */
+   *
+   *  @param   that the `Iterable` whose size is compared with this $coll's size.
+   *  @return  A value `x` where
+   *  {{{
+   *       x <  0       if this.size <  that.size
+   *       x == 0       if this.size == that.size
+   *       x >  0       if this.size >  that.size
+   *  }}}
+   *
+   *  The method as implemented here does not call `size` directly; its running time
+   *  is `O(this.size min that.size)` instead of `O(this.size + that.size)`.
+   *  The method should be overridden if computing `size` is cheap and `knownSize` returns `-1`.
+   */
   def sizeCompare(that: Iterable[_]): Int = {
     val thatKnownSize = that.knownSize
 
@@ -345,39 +344,39 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
   def view(from: Int, until: Int): View[A] = view.slice(from, until)
 
   /** Transposes this $coll of iterable collections into
-    *  a $coll of ${coll}s.
-    *
-    *    The resulting collection's type will be guided by the
-    *    static type of $coll. For example:
-    *
-    *    {{{
-    *    val xs = List(
-    *               Set(1, 2, 3),
-    *               Set(4, 5, 6)).transpose
-    *    // xs == List(
-    *    //         List(1, 4),
-    *    //         List(2, 5),
-    *    //         List(3, 6))
-    *
-    *    val ys = Vector(
-    *               List(1, 2, 3),
-    *               List(4, 5, 6)).transpose
-    *    // ys == Vector(
-    *    //         Vector(1, 4),
-    *    //         Vector(2, 5),
-    *    //         Vector(3, 6))
-    *    }}}
-    *
-    *  $willForceEvaluation
-    *
-    *  @tparam B the type of the elements of each iterable collection.
-    *  @param  asIterable an implicit conversion which asserts that the
-    *          element type of this $coll is an `Iterable`.
-    *  @return a two-dimensional $coll of ${coll}s which has as ''n''th row
-    *          the ''n''th column of this $coll.
-    *  @throws IllegalArgumentException if all collections in this $coll
-    *          are not of the same size.
-    */
+   *  a $coll of ${coll}s.
+   *
+   *  The resulting collection's type will be guided by the
+   *  static type of $coll. For example:
+   *
+   *  {{{
+   *  val xs = List(
+   *             Set(1, 2, 3),
+   *             Set(4, 5, 6)).transpose
+   *  // xs == List(
+   *  //         List(1, 4),
+   *  //         List(2, 5),
+   *  //         List(3, 6))
+   *
+   *  val ys = Vector(
+   *             List(1, 2, 3),
+   *             List(4, 5, 6)).transpose
+   *  // ys == Vector(
+   *  //         Vector(1, 4),
+   *  //         Vector(2, 5),
+   *  //         Vector(3, 6))
+   *  }}}
+   *
+   *  $willForceEvaluation
+   *
+   *  @tparam B the type of the elements of each iterable collection.
+   *  @param  asIterable an implicit conversion which asserts that the
+   *          element type of this $coll is an `Iterable`.
+   *  @return a two-dimensional $coll of ${coll}s which has as ''n''th row
+   *          the ''n''th column of this $coll.
+   *  @throws IllegalArgumentException if all collections in this $coll
+   *          are not of the same size.
+   */
   def transpose[B](implicit asIterable: A => /*<:<!!!*/ Iterable[B]): CC[CC[B] @uncheckedVariance] = {
     if (isEmpty)
       return iterableFactory.empty[CC[B]]
@@ -718,31 +717,31 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
   }
 
   /** Returns a new $ccoll containing the elements from the left hand operand followed by the elements from the
-    *  right hand operand. The element type of the $ccoll is the most specific superclass encompassing
-    *  the element types of the two operands.
-    *
-    *  @param suffix   the iterable to append.
-    *  @tparam B     the element type of the returned collection.
-    *  @return       a new $coll which contains all elements
-    *                of this $coll followed by all elements of `suffix`.
-    */
+   *  right hand operand. The element type of the $ccoll is the most specific superclass encompassing
+   *  the element types of the two operands.
+   *
+   *  @param suffix   the iterable to append.
+   *  @tparam B     the element type of the returned collection.
+   *  @return       a new $coll which contains all elements
+   *                of this $coll followed by all elements of `suffix`.
+   */
   def concat[B >: A](suffix: IterableOnce[B]): CC[B] = iterableFactory.from(suffix match {
     case xs: Iterable[B] => new View.Concat(this, xs)
     case xs => iterator ++ suffix.iterator
   })
 
   /** Alias for `concat` */
-  @`inline` final def ++ [B >: A](suffix: IterableOnce[B]): CC[B] = concat(suffix)
+  @inline final def ++ [B >: A](suffix: IterableOnce[B]): CC[B] = concat(suffix)
 
-  /** Returns a $coll formed from this $coll and another iterable collection
-    *  by combining corresponding elements in pairs.
-    *  If one of the two collections is longer than the other, its remaining elements are ignored.
-    *
-    *  @param   that  The iterable providing the second half of each result pair
-    *  @tparam  B     the type of the second half of the returned pairs
-    *  @return        a new $coll containing pairs consisting of corresponding elements of this $coll and `that`.
-    *                 The length of the returned collection is the minimum of the lengths of this $coll and `that`.
-    */
+  /** Returns a $ccoll formed from this $coll and another iterable collection
+   *  by combining corresponding elements in pairs.
+   *  If one of the two collections is longer than the other, its remaining elements are ignored.
+   *
+   *  @param   that  The iterable providing the second half of each result pair
+   *  @tparam  B     the type of the second half of the returned pairs
+   *  @return        a new $ccoll containing pairs consisting of corresponding elements of this $coll and `that`.
+   *                 The length of the returned collection is the minimum of the lengths of this $coll and `that`.
+   */
   def zip[B](that: IterableOnce[B]): CC[(A @uncheckedVariance, B)] = iterableFactory.from(that match { // sound bcs of VarianceNote
     case that: Iterable[B] => new View.Zip(this, that)
     case _ => iterator.zip(that)

library/src/scala/collection/IterableOnce.scala

@@ -453,36 +453,35 @@ trait IterableOnceOps[+A, +CC[_], +C] extends Any { this: IterableOnce[A] =>
    *    For example:
    *
    *    {{{
-   *      def getWords(lines: Seq[String]): Seq[String] = lines flatMap (line => line split "\\W+")
+   *      def getWords(lines: Seq[String]): Seq[String] = lines.flatMap(line => line.split("\\W+"))
    *    }}}
    *
-   *    The type of the resulting collection is guided by the static type of $coll. This might
+   *    The type of the resulting collection is guided by the static type of this $coll. This might
    *    cause unexpected results sometimes. For example:
    *
    *    {{{
    *      // lettersOf will return a Seq[Char] of likely repeated letters, instead of a Set
-   *      def lettersOf(words: Seq[String]) = words flatMap (word => word.toSet)
+   *      def lettersOf(words: Seq[String]) = words.flatMap(word => word.toSet)
    *
    *      // lettersOf will return a Set[Char], not a Seq
-   *      def lettersOf(words: Seq[String]) = words.toSet flatMap ((word: String) => word.toSeq)
+   *      def lettersOf(words: Seq[String]) = words.toSet.flatMap(word => word.toSeq)
    *
    *      // xs will be an Iterable[Int]
-   *      val xs = Map("a" -> List(11,111), "b" -> List(22,222)).flatMap(_._2)
+   *      val xs = Map("a" -> List(11, 111), "b" -> List(22, 222)).flatMap(_._2)
    *
    *      // ys will be a Map[Int, Int]
-   *      val ys = Map("a" -> List(1 -> 11,1 -> 111), "b" -> List(2 -> 22,2 -> 222)).flatMap(_._2)
+   *      val ys = Map("a" -> List(1 -> 11, 1 -> 111), "b" -> List(2 -> 22, 2 -> 222)).flatMap(_._2)
    *    }}}
    *
    *  @param f      the function to apply to each element.
    *  @tparam B     the element type of the returned collection.
-   *  @return       a new $coll resulting from applying the given collection-valued function
+   *  @return       a new $ccoll resulting from applying the given collection-valued function
    *                `f` to each element of this $coll and concatenating the results.
    */
   def flatMap[B](f: A => IterableOnce[B]): CC[B]
 
-  /** Converts this $coll of iterable collections into
-   *  a $coll formed by the elements of these iterable
-   *  collections.
+  /** Given that the elements of this collection are themselves iterable collections,
+   *  converts this $coll into a $ccoll comprising the elements of these iterable collections.
    *
    *    The resulting collection's type will be guided by the
    *    type of $coll. For example:
@@ -504,24 +503,24 @@ trait IterableOnceOps[+A, +CC[_], +C] extends Any { this: IterableOnce[A] =>
    *  @tparam B the type of the elements of each iterable collection.
    *  @param asIterable an implicit conversion which asserts that the element
    *          type of this $coll is an `Iterable`.
-   *  @return a new $coll resulting from concatenating all element ${coll}s.
+   *  @return a new $ccoll resulting from concatenating all element collections.
    */
   def flatten[B](implicit asIterable: A => IterableOnce[B]): CC[B]
 
-  /** Builds a new $coll by applying a partial function to all elements of this $coll
+  /** Builds a new $ccoll by applying a partial function to all elements of this $coll
    *  on which the function is defined.
    *
    *  @param pf     the partial function which filters and maps the $coll.
    *  @tparam B     the element type of the returned $coll.
-   *  @return       a new $coll resulting from applying the given partial function
+   *  @return       a new $ccoll resulting from applying the given partial function
    *                `pf` to each element on which it is defined and collecting the results.
    *                The order of the elements is preserved.
    */
   def collect[B](pf: PartialFunction[A, B]): CC[B]
 
   /** Zips this $coll with its indices.
    *
-   *  @return        A new $coll containing pairs consisting of all elements of this $coll paired with their index.
+   *  @return        A new $ccoll containing pairs consisting of all elements of this $coll paired with their index.
    *                 Indices start at `0`.
    *  @example
    *    `List("a", "b", "c").zipWithIndex == List(("a", 0), ("b", 1), ("c", 2))`
@@ -532,7 +531,7 @@ trait IterableOnceOps[+A, +CC[_], +C] extends Any { this: IterableOnce[A] =>
    *
    *  Note: `c span p`  is equivalent to (but possibly more efficient than)
    *  `(c takeWhile p, c dropWhile p)`, provided the evaluation of the
-   *  predicate `p` does not cause any side-effects.
+   *  predicate `p` does not cause any side effects.
    *  $orderDependent
    *
    *  @param p the test predicate

library/src/scala/collection/Seq.scala

@@ -180,11 +180,11 @@ trait SeqOps[+A, +CC[_], +C] extends Any
   def appendedAll[B >: A](suffix: IterableOnce[B]): CC[B] = super.concat(suffix)
 
   /** Alias for `appendedAll`. */
-  @`inline` final def :++ [B >: A](suffix: IterableOnce[B]): CC[B] = appendedAll(suffix)
+  @inline final def :++ [B >: A](suffix: IterableOnce[B]): CC[B] = appendedAll(suffix)
 
   // Make `concat` an alias for `appendedAll` so that it benefits from performance
   // overrides of this method
-  @`inline` final override def concat[B >: A](suffix: IterableOnce[B]): CC[B] = appendedAll(suffix)
+  @inline final override def concat[B >: A](suffix: IterableOnce[B]): CC[B] = appendedAll(suffix)
 
  /** Produces a new sequence which contains all elements of this $coll and also all elements of
    *  a given sequence. `xs union ys`  is equivalent to `xs ++ ys`.
@@ -286,7 +286,7 @@ trait SeqOps[+A, +CC[_], +C] extends Any
    *  @param   len   the target length
    *  @param   elem  the padding value
    *  @tparam B      the element type of the returned $coll.
-   *  @return a new $coll consisting of
+   *  @return a new $ccoll consisting of
    *          all elements of this $coll followed by the minimal number of occurrences of `elem` so
    *          that the resulting collection has a length of at least `len`.
    */