Added more comments to make things easier to understand and maintain

core/src/main/scala/scala/collection/generic/GenericParCompanion.scala

@@ -28,6 +28,9 @@ import scala.language.{higherKinds, implicitConversions}
  */
 trait GenericParCompanion[+CC[X] <: ParIterable[X]] {
 
+  // `empty` and `apply` were previously inherited from `GenericCompanion` but this class
+  // has been removed in 2.13. I’ve copied their old implementation here.
+
   /** An empty collection of type `$Coll[A]`
     *  @tparam A      the type of the ${coll}'s elements
     */

core/src/main/scala/scala/collection/generic/ParFactory.scala

@@ -30,6 +30,9 @@ import scala.language.higherKinds
 abstract class ParFactory[CC[X] <: ParIterable[X] with GenericParTemplate[X, CC]]
 extends GenericParCompanion[CC] {
 
+  // The methods below were previously inherited from `GenTraversableFactory`, but this
+  // class has been removed in 2.13.
+
   /** Concatenates all argument collections into a single $coll.
    *
    *  @param xss the collections that are to be concatenated.

core/src/main/scala/scala/collection/generic/ParMapFactory.scala

@@ -35,6 +35,9 @@ extends GenericParMapCompanion[CC] {
 
   type Coll = MapColl
 
+  // `apply` and `empty` methods were previously inherited from `GenMapFactory`, which
+  // has been removed from the Scala library in 2.13
+
   /** A collection of type $Coll that contains given key/value bindings.
     *  @param elems   the key/value pairs that make up the $coll
     *  @tparam K      the type of the keys

core/src/main/scala/scala/collection/parallel/ParMapLike.scala

@@ -191,6 +191,9 @@ self =>
     def - (key: K): ParMap[K, S] = ParMap[K, S]() ++ this - key
   }
 
+  // Transformation operations (`map`, `collect`, `flatMap` and `concat`) are overloaded
+  // to return a `ParMap` rather than a `ParIterable`
+
   /** Builds a new map by applying a function to all elements of this $coll.
     *
     *  @param f      the function to apply to each element.

core/src/main/scala/scala/collection/parallel/ParSeqLike.scala

@@ -325,6 +325,7 @@ self =>
     */
   def endsWith[S >: T](that: Iterable[S]): Boolean = seq.endsWith(that)
 
+  /** Overload of ''patch'' that takes a sequential collection as parameter */
   def patch[U >: T](from: Int, patch: scala.collection.Seq[U], replaced: Int): CC[U] = patch_sequential(from, patch, replaced)
 
   def patch[U >: T](from: Int, patch: ParSeq[U], replaced: Int): CC[U] = {
@@ -387,9 +388,11 @@ self =>
     *  @return       a new $coll which contains all elements of this $coll
     *                  followed by all elements of `that`.
     */
-  def union[B >: T](that: scala.collection.Seq[B]): CC[B] = this ++ that
   def union[B >: T](that: ParSeq[B]): CC[B] = this ++ that
 
+  /** Overload of ''union'' that takes a sequential collection as parameter */
+  def union[B >: T](that: scala.collection.Seq[B]): CC[B] = this ++ that
+
   def padTo[U >: T](len: Int, elem: U): CC[U] = if (length < len) {
     patch(length, new immutable.Repetition(elem, len - length), 0)
   } else patch(length, ParSeq.newBuilder[U].result(), 0)

junit/src/test/scala/MiscTest.scala

@@ -24,7 +24,9 @@ class MiscTest {
   def si4761: Unit = {
     val gs = for (x <- (1 to 5)) yield { if (x % 2 == 0) List(1) else List(1).par }
     assertEquals("Vector(1, 1, 1, 1, 1)", gs.flatten.toString)
-//    assertEquals("Vector(Vector(1, 1, 1, 1, 1))", gs.transpose.toString)
+    // Commented because `transpose` require its argument to be convertible to an `Iterable` whereas
+    // we only have an `IterableOnce`
+    // assertEquals("Vector(Vector(1, 1, 1, 1, 1))", gs.transpose.toString)
 
     val s = LazyList(Vector(1).par, Vector(2).par)
     assertEquals("List(1, 2)", s.flatten.toList.toString)
@@ -86,6 +88,7 @@ class MiscTest {
     def check[T](i: Int, f: Int => T): Unit = {
       val gseq = seqarr(i).toSeq.groupBy(f)
       val gpar = pararr(i).groupBy(f)
+      // Note: sequential and parallel collections can not be compared with ''==''
       assertTrue(gseq.forall { case (k, vs) => gpar.get(k).exists(_.sameElements(vs)) })
       assertTrue(gpar.forall { case (k, vs) => gseq.get(k).exists(_.sameElements(vs)) })
     }