Collection mutable (2): filled in @param, @tparam, and @return tags that were missed last time

library-js/src/scala/collection/mutable/ArrayBuilder.scala

@@ -57,6 +57,7 @@ sealed abstract class ArrayBuilder[T]
   /** Adds all elements of an array.
    *
    *  @param xs the array from which to add elements
+   *  @return this builder with the elements of `xs` appended
    */
   def addAll(xs: Array[_ <: T]): this.type = addAll(xs, 0, xs.length)
 
@@ -65,6 +66,7 @@ sealed abstract class ArrayBuilder[T]
    *  @param xs the array from which to add a slice of elements
    *  @param offset the starting index in `xs` from which to copy elements
    *  @param length the number of elements to copy from `xs`
+   *  @return this builder with the specified slice of `xs` appended
    */
   def addAll(xs: Array[_ <: T], offset: Int, length: Int): this.type = {
     ensureSize(this.size + length)
@@ -106,6 +108,7 @@ object ArrayBuilder {
   /** Implementation of `make` for JS.
    *
    *  @tparam T the element type of the array builder, with a `ClassTag` context bound
+   *  @return a new generic `ArrayBuilder` optimized for Scala.js
    */
   @inline
   private def makeForJS[T: ClassTag]: ArrayBuilder[T] =
@@ -165,6 +168,7 @@ object ArrayBuilder {
      *  @param xs the array from which to add a slice of elements
      *  @param offset the starting index in `xs` from which to copy elements
      *  @param length the number of elements to copy from `xs`
+     *  @return this builder with the specified slice of `xs` appended
      */
     override def addAll(xs: Array[_ <: T], offset: Int, length: Int): this.type = {
       val end = offset + length

library-js/src/scala/collection/mutable/Buffer.scala

@@ -43,14 +43,17 @@ trait Buffer[A]
   /** Appends the given elements to this buffer.
    *
    *  @param elem  the element to append.
+   *  @return this buffer with the element appended
    */
   @`inline` final def append(elem: A): this.type = addOne(elem)
 
   @deprecated("Use appendAll instead", "2.13.0")
   @`inline` final def append(elems: A*): this.type = addAll(elems)
 
   /** Appends the elements contained in a iterable object to this buffer.
+   *
    *  @param xs  the iterable object containing the elements to append.
+   *  @return this buffer with the elements appended
    */
   @`inline` final def appendAll(xs: IterableOnce[A]): this.type = addAll(xs)
 

library/src/scala/collection/mutable/AnyRefMap.scala

@@ -222,16 +222,21 @@ class AnyRefMap[K <: AnyRef, V] private[collection] (defaultEntry: K -> V, initi
    *  `defaultEntry` was supplied.
    *
    *  @param key the key to look up
+   *  @return the value associated with `key`, or the result of `defaultEntry(key)` if the key is not present
    */
   override def apply(key: K): V = {
     val i = seekEntry(hashOf(key), key)
     if (i < 0) defaultEntry(key) else _values(i).asInstanceOf[V]
   }
 
-  /** Defers to defaultEntry to find a default value for the key.  Throws an
-   *  exception if no other default behavior was specified.
+  /** Returns a default value for `key` by applying `defaultEntry`.
+   *
+   *  If this map was created without a user-supplied `defaultEntry`
+   *  (e.g. via `new AnyRefMap()` or `new AnyRefMap(initialBufferSize)`),
+   *  the `apply` method of `defaultEntry` will always throw `NoSuchElementException`.
    *
    *  @param key the key to look up a default value for
+   *  @return the default value supplied by `defaultEntry` for `key`, or throws `NoSuchElementException` if no `defaultEntry` was provided
    */
   override def default(key: K): V = defaultEntry(key)
 
@@ -328,6 +333,7 @@ class AnyRefMap[K <: AnyRef, V] private[collection] (defaultEntry: K -> V, initi
    *
    *  @param key the key to add
    *  @param value the value to associate with `key`
+   *  @return this map after the entry has been added
    */
   @inline final def addOne(key: K, value: V): this.type = { update(key, value); this }
 
@@ -476,6 +482,7 @@ class AnyRefMap[K <: AnyRef, V] private[collection] (defaultEntry: K -> V, initi
    *
    *  @tparam V1 the new value type
    *  @param f the transformation function to apply to each value
+   *  @return a new `AnyRefMap` with the same keys and values transformed by `f`
    */
   def mapValuesNow[V1](f: V => V1): AnyRefMap[K, V1] = {
     val arm = new AnyRefMap[K,V1](AnyRefMap.exceptionDefault, 1, initBlank = false)
@@ -505,6 +512,7 @@ class AnyRefMap[K <: AnyRef, V] private[collection] (defaultEntry: K -> V, initi
    *  Note: the default, if any,  is not transformed.
    *
    *  @param f the transformation function to apply to each value
+   *  @return this map after each stored value has been replaced by `f` applied to it
    */
   def transformValuesInPlace(f: V => V): this.type = {
     var i,j = 0
@@ -527,6 +535,7 @@ class AnyRefMap[K <: AnyRef, V] private[collection] (defaultEntry: K -> V, initi
    *  @tparam V2 the value type of the resulting map
    *  @param f the function mapping each key-value pair to a new key-value pair; the resulting key must be an `AnyRef`
    *  @param dummy implicit parameter used to distinguish this overload from the inherited version after erasure
+   *  @return a new `AnyRefMap` containing the key-value pairs produced by applying `f` to each entry of this map
    */
   def map[K2 <: AnyRef, V2](f: ((K, V)) => (K2, V2))(implicit dummy: DummyImplicit): AnyRefMap[K2, V2] =
     AnyRefMap.from(new View.Map(this, f))
@@ -536,6 +545,7 @@ class AnyRefMap[K <: AnyRef, V] private[collection] (defaultEntry: K -> V, initi
    *  @tparam V2 the value type of the resulting map
    *  @param f the function mapping each key-value pair to a collection of new key-value pairs; the resulting keys must be `AnyRef`s
    *  @param dummy implicit parameter used to distinguish this overload from the inherited version after erasure
+   *  @return a new `AnyRefMap` containing all the key-value pairs produced by applying `f` to each entry of this map
    */
   def flatMap[K2 <: AnyRef, V2](f: ((K, V)) => IterableOnce[(K2, V2)]^)(implicit dummy: DummyImplicit): AnyRefMap[K2, V2] =
     AnyRefMap.from(new View.FlatMap(this, f))
@@ -545,6 +555,7 @@ class AnyRefMap[K <: AnyRef, V] private[collection] (defaultEntry: K -> V, initi
    *  @tparam V2 the value type of the resulting map
    *  @param pf the partial function mapping key-value pairs to new key-value pairs; the resulting key must be an `AnyRef`
    *  @param dummy implicit parameter used to distinguish this overload from the inherited version after erasure
+   *  @return a new `AnyRefMap` containing the key-value pairs produced by applying `pf` to each entry on which it is defined
    */
   def collect[K2 <: AnyRef, V2](pf: PartialFunction[(K, V), (K2, V2)])(implicit dummy: DummyImplicit): AnyRefMap[K2, V2] =
     strictOptimizedCollect(AnyRefMap.newBuilder[K2, V2], pf)
@@ -599,6 +610,7 @@ object AnyRefMap {
    *  @tparam K the type of keys, must be a subtype of `AnyRef`
    *  @tparam V the type of values
    *  @param elems the key-value pairs to initialize the map with
+   *  @return a new `AnyRefMap` containing the given key-value pairs
    */
   def apply[K <: AnyRef, V](elems: (K, V)*): AnyRefMap[K, V] = buildFromIterableOnce(elems)
 
@@ -617,6 +629,7 @@ object AnyRefMap {
    *
    *  @tparam K the type of keys, must be a subtype of `AnyRef`
    *  @tparam V the type of values
+   *  @return a new empty `AnyRefMap`
    */
   def empty[K <: AnyRef, V]: AnyRefMap[K, V] = new AnyRefMap[K, V]
 
@@ -625,6 +638,7 @@ object AnyRefMap {
    *  @tparam K the type of keys, must be a subtype of `AnyRef`
    *  @tparam V the type of values
    *  @param default the function mapping keys to default values
+   *  @return a new empty `AnyRefMap` that uses `default` to supply values for missing keys
    */
   def withDefault[K <: AnyRef, V](default: K -> V): AnyRefMap[K, V] = new AnyRefMap[K, V](default)
 
@@ -648,6 +662,7 @@ object AnyRefMap {
    *  @tparam V the type of values
    *  @param keys the array of keys
    *  @param values the array of values, paired positionally with `keys`
+   *  @return a new `AnyRefMap` containing entries `keys(i) -> values(i)` for indices up to the shorter array's length
    */
   def fromZip[K <: AnyRef, V](keys: Array[K], values: Array[V]): AnyRefMap[K, V] = {
     val sz = math.min(keys.length, values.length)
@@ -665,6 +680,7 @@ object AnyRefMap {
    *  @tparam V the type of values
    *  @param keys the collection of keys
    *  @param values the collection of values, paired positionally with `keys`
+   *  @return a new `AnyRefMap` containing the entries formed by pairing each key with the value at the same position, up to the shorter collection's size
    */
   def fromZip[K <: AnyRef, V](keys: Iterable[K], values: Iterable[V]): AnyRefMap[K, V] = {
     val sz = math.min(keys.size, values.size)

library/src/scala/collection/mutable/ArrayBuffer.scala

@@ -138,6 +138,7 @@ class ArrayBuffer[A] private (initialElements: Array[AnyRef], initialSize: Int)
   /** Clears this buffer and shrinks to @param size (rounding up to the next
    *  natural size)
    *  @param size
+   *  @return this `ArrayBuffer`, now empty and resized to a capacity at least as large as `size`
    */
   def clearAndShrink(size: Int = ArrayBuffer.DefaultInitialSize): this.type = {
     clear()
@@ -211,6 +212,9 @@ class ArrayBuffer[A] private (initialElements: Array[AnyRef], initialSize: Int)
 
   /** Note: This does not actually resize the internal representation.
    *  See trimToSize if you want to also resize internally
+   *
+   *  @param index the zero-based position of the element to remove
+   *  @return the element that was removed at position `index`
    */
   def remove(@deprecatedName("n", "2.13.0") index: Int): A = {
     checkWithinBounds(index, index + 1)
@@ -222,6 +226,9 @@ class ArrayBuffer[A] private (initialElements: Array[AnyRef], initialSize: Int)
 
   /** Note: This does not actually resize the internal representation.
    *  See trimToSize if you want to also resize internally
+   *
+   *  @param index the zero-based position of the first element to remove
+   *  @param count the number of elements to remove; a negative value throws `IllegalArgumentException`
    */
   def remove(@deprecatedName("n", "2.13.0") index: Int, count: Int): Unit =
     if (count > 0) {

library/src/scala/collection/mutable/ArrayBuilder.scala

@@ -50,6 +50,7 @@ sealed abstract class ArrayBuilder[T]
   /** Adds all elements of an array.
    *
    *  @param xs the array of elements to add
+   *  @return this builder with the elements of `xs` appended
    */
   def addAll(xs: Array[? <: T]): this.type = addAll(xs, 0, xs.length)
 
@@ -58,6 +59,7 @@ sealed abstract class ArrayBuilder[T]
    *  @param xs the array from which a slice of elements is added
    *  @param offset the start index within `xs` from which to copy elements (clamped to 0 if negative)
    *  @param length the maximum number of elements to copy from `xs` (clamped to 0 if negative, and to the number of available elements)
+   *  @return this builder with the selected slice of `xs` appended
    */
   def addAll(xs: Array[? <: T], offset: Int, length: Int): this.type = {
     val offset1 = offset.max(0)

library/src/scala/collection/mutable/ArrayDeque.scala

@@ -585,16 +585,16 @@ transparent trait ArrayDequeOps[A, +CC[_] <: caps.Pure, +C <: AnyRef] extends St
     if (idx < 0 || idx >= until)
       throw CommonErrors.indexOutOfBounds(index = idx, max = until - 1)
 
-  /**
-    * This is a more general version of copyToArray - this also accepts a srcStart unlike copyToArray
-    * This copies maxItems elements from this collections srcStart to dest's destStart
-    * If we reach the end of either collections before we could copy maxItems, we simply stop copying
-    *
-    * @param dest
-    * @param srcStart
-    * @param destStart
-    * @param maxItems
-    */
+  /** This is a more general version of copyToArray - this also accepts a srcStart unlike copyToArray
+   *  This copies maxItems elements from this collection's srcStart to dest's destStart
+   *  If we reach the end of either collections before we could copy maxItems, we simply stop copying
+   *
+   *  @param dest
+   *  @param srcStart
+   *  @param destStart
+   *  @param maxItems
+   *  @return the `dest` array, after the copied elements have been written into it
+   */
   def copySliceToArray(srcStart: Int, dest: Array[?], destStart: Int, maxItems: Int): dest.type = {
     requireBounds(destStart, dest.length+1)
     val toCopy = Math.min(maxItems, Math.min(length - srcStart, dest.length - destStart))

library/src/scala/collection/mutable/ArraySeq.scala

@@ -58,7 +58,11 @@ sealed abstract class ArraySeq[T]
    */
   def elemTag: ClassTag[?]
 
-  /** Updates element at given index. */
+  /** Updates element at given index.
+   *
+   *  @param index the zero-based position of the element to update
+   *  @param elem the new value to store at the given index
+   */
   def update(@deprecatedName("idx", "2.13.0") index: Int, elem: T): Unit
 
   /** The underlying array. Its element type does not have to be equal to the element type of this ArraySeq. A primitive

library/src/scala/collection/mutable/BitSet.scala

@@ -373,6 +373,7 @@ object BitSet extends SpecificIterableFactory[Int, BitSet] {
   /** A bitset containing all the bits in an array.
    *
    *  @param elems the array of `Long` words representing the bits; a defensive copy is made
+   *  @return a new bitset backed by a copy of `elems`
    */
   def fromBitMask(elems: Array[Long]): BitSet = {
     val len = elems.length
@@ -387,6 +388,7 @@ object BitSet extends SpecificIterableFactory[Int, BitSet] {
    *  array without copying.
    *
    *  @param elems the array of `Long` words representing the bits, used directly without copying; the caller must not mutate the array afterward
+   *  @return a new bitset backed directly by `elems`
    */
   def fromBitMaskNoCopy(elems: Array[Long]): BitSet = {
     val len = elems.length

library/src/scala/collection/mutable/Builder.scala

@@ -106,6 +106,7 @@ trait Builder[-A, +To] extends Growable[A] { self: Builder[A, To]^ =>
    *
    *  @tparam NewTo the type of collection produced by the returned builder
    *  @param f the function to apply to this builder's result
+   *  @return a new builder that delegates element additions to this builder and applies `f` to the result
    */
   def mapResult[NewTo](f: To => NewTo): Builder[A, NewTo]^{this, f} = new Builder[A, NewTo] {
     def addOne(x: A): this.type = { self += x; this }

library/src/scala/collection/mutable/CollisionProofHashMap.scala

@@ -39,6 +39,7 @@ import scala.runtime.Statics
  *  @tparam V the type of the values associated with the keys
  *  @param initialCapacity the initial capacity of the internal hash table
  *  @param loadFactor the load factor for the hash table, used to determine when to resize
+ *  @param ordering the `Ordering` used to compare keys within a bucket's red-black tree
  */
 final class CollisionProofHashMap[K, V](initialCapacity: Int, loadFactor: Double)(implicit ordering: Ordering[K])
   extends AbstractMap[K, V]
@@ -714,6 +715,7 @@ final class CollisionProofHashMap[K, V](initialCapacity: Int, loadFactor: Double
    *  @param _root the root of the red-black tree
    *  @param to the node to be replaced in the tree
    *  @param from the node that replaces `to`
+   *  @return the (possibly updated) root of the tree, which differs from `_root` only when `to` was the root
    */
   private def transplant(_root: RBNode, to: RBNode, from: RBNode): RBNode = {
     var root = _root
@@ -859,6 +861,7 @@ object CollisionProofHashMap extends SortedMapFactory[CollisionProofHashMap] {
    *  @tparam A the key type of the tree nodes
    *  @tparam B the value type of the tree nodes
    *  @param node the node whose successor is to be found
+   *  @return the in-order successor of `node`, or `null` if `node` is the last node in the traversal
    */
   private def successor[A, B](node: RBNode[A, B]): RBNode[A, B] | Null = {
     if (node.right ne null) minNodeNonNull(node.right)

library/src/scala/collection/mutable/GrowableBuilder.scala

@@ -26,6 +26,7 @@ import language.experimental.captureChecking
  *
  *  @tparam Elem the type of elements that can be added to the builder
  *  @tparam To the type of the resulting growable collection, which must be a subtype of `Growable[Elem]`
+ *  @param elems the underlying growable collection that elements are added to and which is returned as the result
  */
 class GrowableBuilder[Elem, To <: Growable[Elem]](protected val elems: To)
   extends Builder[Elem, To] {

library/src/scala/collection/mutable/HashMap.scala

@@ -65,12 +65,14 @@ class HashMap[K, V](initialCapacity: Int, loadFactor: Double)
   /** Performs the inverse operation of improveHash. In this case, it happens to be identical to improveHash.
    *
    *  @param improvedHash the improved hash value to convert back to the original `any.##` hash
+   *  @return the original `any.##` hash code corresponding to `improvedHash`
    */
   @`inline` private[collection] def unimproveHash(improvedHash: Int): Int = improveHash(improvedHash)
 
   /** Computes the improved hash of an original (`any.##`) hash.
    *
    *  @param originalHash the original hash code from `any.##`
+   *  @return the improved hash with the high 16 bits xored into the low 16 bits
    */
   @`inline` private def improveHash(originalHash: Int): Int = {
     // Improve the hash by xoring the high 16 bits into the low 16 bits just in case entropy is skewed towards the
@@ -86,6 +88,7 @@ class HashMap[K, V](initialCapacity: Int, loadFactor: Double)
   /** Computes the improved hash of this key.
    *
    *  @param o the key for which to compute the improved hash
+   *  @return the improved hash code of `o` (i.e., `improveHash(o.##)`)
    */
   @`inline` private def computeHash(o: K): Int = improveHash(o.##)
 
@@ -235,6 +238,7 @@ class HashMap[K, V](initialCapacity: Int, loadFactor: Double)
    *  @param value the value to add
    *  @param hash the **improved** hashcode of `key` (see computeHash)
    *  @param getOld if true, then the previous value for `key` will be returned, otherwise, false
+   *  @return `Some` wrapping the previous value if `getOld` is true and `key` was already present; `null` otherwise (i.e., when `getOld` is false or `key` was not in the map)
    */
   private def put0(key: K, value: V, hash: Int, getOld: Boolean): Some[V] | Null = {
     if(contentSize + 1 >= threshold) growTable(table.length * 2)

library/src/scala/collection/mutable/HashSet.scala

@@ -64,12 +64,14 @@ final class HashSet[A](initialCapacity: Int, loadFactor: Double)
   /** Performs the inverse operation of improveHash. In this case, it happens to be identical to improveHash.
    *
    *  @param improvedHash the improved hash value to convert back to a standard hash index
+   *  @return the hash index recovered by re-applying the improvement transformation (which happens to be its own inverse)
    */
   @`inline` private[collection] def unimproveHash(improvedHash: Int): Int = improveHash(improvedHash)
 
   /** Computes the improved hash of an original (`any.##`) hash.
    *
    *  @param originalHash the original hash code obtained from `##`
+   *  @return the improved hash, with high bits XORed into the low bits to spread entropy into the bits used for bucket indexing
    */
   private def improveHash(originalHash: Int): Int = {
     // Improve the hash by xoring the high 16 bits into the low 16 bits just in case entropy is skewed towards the
@@ -81,6 +83,7 @@ final class HashSet[A](initialCapacity: Int, loadFactor: Double)
   /** Computes the improved hash of this element.
    *
    *  @param o the element whose hash to compute
+   *  @return the improved hash of `o`, computed from `o.##`
    */
   @`inline` private def computeHash(o: A): Int = improveHash(o.##)
 
@@ -163,8 +166,10 @@ final class HashSet[A](initialCapacity: Int, loadFactor: Double)
   }
 
   /** Adds an element to this set.
+   *
    *  @param elem element to add
    *  @param hash the **improved** hash of `elem` (see computeHash)
+   *  @return `true` if `elem` was added to the set, or `false` if an equal element was already present
    */
   private def addElem(elem: A, hash: Int) : Boolean = {
     val idx = index(hash)