Find more doc vars and distinguish C from CC

Author: som-snytt

library/src/scala/collection/Factory.scala

@@ -90,7 +90,7 @@ trait IterableFactory[+CC[_]] extends Serializable {
     */
   def from[A](source: IterableOnce[A]): CC[A]
 
-  /** An empty collection
+  /** An empty $coll
     * @tparam A      the type of the ${coll}'s elements
     */
   def empty[A]: CC[A]

library/src/scala/collection/Iterable.scala

@@ -717,8 +717,8 @@ trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] with Iterable
     (iterableFactory.from(left), iterableFactory.from(right))
   }
 
-  /** Returns a new $coll containing the elements from the left hand operand followed by the elements from the
-    *  right hand operand. The element type of the $coll is the most specific superclass encompassing
+  /** 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.
@@ -862,7 +862,7 @@ object IterableOps {
   /** Operations for comparing the size of a collection to a test value.
     *
     * These operations are implemented in terms of
-    * [[scala.collection.IterableOps.sizeCompare(Int) `sizeCompare(Int)`]].
+    * [[scala.collection.IterableOps!.sizeCompare(Int):Int* `sizeCompare(Int)`]]
     */
   final class SizeCompareOps private[collection](val it: IterableOps[_, AnyConstr, _]) extends AnyVal {
     /** Tests if the size of the collection is less than some value. */

library/src/scala/collection/IterableOnce.scala

@@ -40,6 +40,7 @@ import scala.runtime.{AbstractFunction1, AbstractFunction2}
   * without inheriting unwanted implementations.
   *
   * @define coll collection
+  * @define ccoll $coll
   */
 trait IterableOnce[+A] extends Any {
 
@@ -318,8 +319,6 @@ object IterableOnce {
   *              The order of applications of the operator is unspecified and may be nondeterministic.
   * @define exactlyOnce
   *              Each element appears exactly once in the computation.
-  * @define coll collection
-  *
   */
 trait IterableOnceOps[+A, +CC[_], +C] extends Any { this: IterableOnce[A] =>
   /////////////////////////////////////////////////////////////// Abstract methods that must be implemented
@@ -439,16 +438,16 @@ trait IterableOnceOps[+A, +CC[_], +C] extends Any { this: IterableOnce[A] =>
    */
   def slice(from: Int, until: Int): C
 
-  /** Builds a new $coll by applying a function to all elements of this $coll.
+  /** Builds a new $ccoll by applying a function to all elements of this $coll.
    *
    *  @param f      the function to apply to each element.
-   *  @tparam B     the element type of the returned $coll.
-   *  @return       a new $coll resulting from applying the given function
+   *  @tparam B     the element type of the returned $ccoll.
+   *  @return       a new $ccoll resulting from applying the given function
    *                `f` to each element of this $coll and collecting the results.
    */
   def map[B](f: A => B): CC[B]
 
-  /** Builds a new $coll by applying a function to all elements of this $coll
+  /** Builds a new $ccoll by applying a function to all elements of this $coll
    *  and using the elements of the resulting collections.
    *
    *    For example:

library/src/scala/collection/Iterator.scala

@@ -844,17 +844,14 @@ trait Iterator[+A] extends IterableOnce[A] with IterableOnceOps[A, Iterator, Ite
    *  @param that  the collection to compare
    *  @tparam B    the type of the elements of collection `that`.
    *  @return `true` if both collections contain equal elements in the same order, `false` otherwise.
-   *
-   *    @inheritdoc
    */
   def sameElements[B >: A](that: IterableOnce[B]): Boolean = {
     val those = that.iterator
-    while (hasNext && those.hasNext)
-      if (next() != those.next())
-        return false
-    // At that point we know that *at least one* iterator has no next element
-    // If *both* of them have no elements then the collections are the same
-    hasNext == those.hasNext
+    while (hasNext) {
+      if (!those.hasNext) return false
+      if (next() != those.next()) return false
+    }
+    !those.hasNext
   }
 
   /** Creates two new iterators that both iterate over the same elements

library/src/scala/collection/Seq.scala

@@ -843,16 +843,23 @@ trait SeqOps[+A, +CC[_], +C] extends Any
 
   override def isEmpty: Boolean = lengthCompare(0) == 0
 
-  /** Tests whether the elements of this collection are the same (and in the same order)
-    * as those of `that`.
-    */
+  /** Checks whether corresponding elements of the given iterable collection
+   *  compare equal (with respect to `==`) to elements of this $coll.
+   *
+   *  @param that  the collection to compare
+   *  @tparam B    the type of the elements of collection `that`.
+   *  @return `true` if both collections contain equal elements in the same order, `false` otherwise.
+   */
   def sameElements[B >: A](that: IterableOnce[B]): Boolean = {
     val thisKnownSize = knownSize
-    val knownSizeDifference = thisKnownSize != -1 && {
+    if (thisKnownSize != -1) {
       val thatKnownSize = that.knownSize
-      thatKnownSize != -1 && thisKnownSize != thatKnownSize
+      if (thatKnownSize != -1) {
+        if (thisKnownSize != thatKnownSize) return false
+        if (thisKnownSize == 0) return true
+      }
     }
-    !knownSizeDifference && iterator.sameElements(that)
+    iterator.sameElements(that)
   }
 
   /** Tests whether every element of this $coll relates to the

library/src/scala/collection/Set.scala

@@ -210,9 +210,7 @@ trait SetOps[A, +CC[_], +C <: SetOps[A, CC, C]]
   @deprecated("Use &- with an explicit collection argument instead of - with varargs", "2.13.0")
   def - (elem1: A, elem2: A, elems: A*): C = diff(elems.toSet + elem1 + elem2)
 
-  /** Creates a new $coll by adding all elements contained in another collection to this $coll, omitting duplicates.
-    *
-    * This method takes a collection of elements and adds all elements, omitting duplicates, into $coll.
+  /** Creates a new $ccoll by adding all elements contained in another collection to this $coll, omitting duplicates.
     *
     * Example:
     *  {{{

library/src/scala/collection/SortedSet.scala

@@ -57,6 +57,7 @@ trait SortedSetOps[A, +CC[X] <: SortedSet[X], +C <: SortedSetOps[A, CC, C]]
     */
   def sortedIterableFactory: SortedIterableFactory[CC]
 
+  /** Widens the type of this set to its unsorted counterpart. */
   def unsorted: Set[A]
 
   /**

library/src/scala/collection/immutable/Range.scala

@@ -20,42 +20,43 @@ import scala.collection.{AbstractIterator, AnyStepper, IterableFactoryDefaults,
 import scala.util.hashing.MurmurHash3
 
 /** The `Range` class represents integer values in range
-  *  ''[start;end)'' with non-zero step value `step`.
-  *  It's a special case of an indexed sequence.
-  *  For example:
-  *
-  *  {{{
-  *     val r1 = 0 until 10
-  *     val r2 = r1.start until r1.end by r1.step + 1
-  *     println(r2.length) // = 5
-  *  }}}
-  *
-  *  Ranges that contain more than `Int.MaxValue` elements can be created, but
-  *  these overfull ranges have only limited capabilities. Any method that
-  *  could require a collection of over `Int.MaxValue` length to be created, or
-  *  could be asked to index beyond `Int.MaxValue` elements will throw an
-  *  exception. Overfull ranges can safely be reduced in size by changing
-  *  the step size (e.g. `by 3`) or taking/dropping elements. `contains`,
-  *  `equals`, and access to the ends of the range (`head`, `last`, `tail`,
-  *  `init`) are also permitted on overfull ranges.
-  *
-  *  @param start       the start of this range.
-  *  @param end         the end of the range.  For exclusive ranges, e.g.
-  *                     `Range(0,3)` or `(0 until 3)`, this is one
-  *                     step past the last one in the range.  For inclusive
-  *                     ranges, e.g. `Range.inclusive(0,3)` or `(0 to 3)`,
-  *                     it may be in the range if it is not skipped by the step size.
-  *                     To find the last element inside a non-empty range,
-  *                     use `last` instead.
-  *  @param step        the step for the range.
-  *
-  *  @define coll range
-  *  @define mayNotTerminateInf
-  *  @define willNotTerminateInf
-  *  @define doesNotUseBuilders
-  *    '''Note:''' this method does not use builders to construct a new range,
-  *         and its complexity is O(1).
-  */
+ *  ''[start;end)'' with non-zero step value `step`.
+ *  It's a special case of an indexed sequence.
+ *  For example:
+ *
+ *  {{{
+ *     val r1 = 0 until 10
+ *     val r2 = r1.start until r1.end by r1.step + 1
+ *     println(r2.length) // = 5
+ *  }}}
+ *
+ *  Ranges that contain more than `Int.MaxValue` elements can be created, but
+ *  these overfull ranges have only limited capabilities. Any method that
+ *  could require a collection of over `Int.MaxValue` length to be created, or
+ *  could be asked to index beyond `Int.MaxValue` elements will throw an
+ *  exception. Overfull ranges can safely be reduced in size by changing
+ *  the step size (e.g. `by 3`) or taking/dropping elements. `contains`,
+ *  `equals`, and access to the ends of the range (`head`, `last`, `tail`,
+ *  `init`) are also permitted on overfull ranges.
+ *
+ *  @param start       the start of this range.
+ *  @param end         the end of the range.  For exclusive ranges, e.g.
+ *                     `Range(0,3)` or `(0 until 3)`, this is one
+ *                     step past the last one in the range.  For inclusive
+ *                     ranges, e.g. `Range.inclusive(0,3)` or `(0 to 3)`,
+ *                     it may be in the range if it is not skipped by the step size.
+ *                     To find the last element inside a non-empty range,
+ *                     use `last` instead.
+ *  @param step        the step for the range.
+ *
+ *  @define coll range
+ *  @define ccoll indexed sequence
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
+ *  @define doesNotUseBuilders
+ *    '''Note:''' this method does not use builders to construct a new range,
+ *         and its complexity is O(1).
+ */
 @SerialVersionUID(3L)
 sealed abstract class Range(
   val start: Int,
@@ -522,11 +523,7 @@ sealed abstract class Range(
     }
 }
 
-/**
-  * Companion object for ranges.
-  *  @define Coll `Range`
-  *  @define coll range
-  */
+/** Companion object for ranges. */
 object Range {
 
   /** Counts the number of range elements.

library/src/scala/collection/mutable/SortedSet.scala

@@ -14,9 +14,8 @@ package scala
 package collection
 package mutable
 
-/**
-  * Base type for mutable sorted set collections
-  */
+/** Base type for mutable sorted set collections
+ */
 trait SortedSet[A]
   extends Set[A]
     with collection.SortedSet[A]
@@ -30,7 +29,7 @@ trait SortedSet[A]
 
 /**
   * @define coll mutable sorted set
-  * @define Coll `mutable.Sortedset`
+  * @define Coll `mutable.SortedSet`
   */
 trait SortedSetOps[A, +CC[X] <: SortedSet[X], +C <: SortedSetOps[A, CC, C]]
   extends SetOps[A, Set, C]
@@ -41,8 +40,8 @@ trait SortedSetOps[A, +CC[X] <: SortedSet[X], +C <: SortedSetOps[A, CC, C]]
 
 /**
   * $factoryInfo
-  * @define coll mutable sorted set
-  * @define Coll `mutable.Sortedset`
+  * @define xcoll mutable sorted set
+  * @define xColl `mutable.SortedSet`
   */
 @SerialVersionUID(3L)
 object SortedSet extends SortedIterableFactory.Delegate[SortedSet](TreeSet)