Collection immutable (3): fill in missing @param, @tparam, and @return tags in Scaladoc comments (#25373)

As a next step in improving the Scaladoc documentation for the Scala 3
standard library, this PR fills in missing @param, @tparam, and @return
tags for collection immutable.

Author: bvenners

library-js/src/scala/collection/immutable/NumericRange.scala

@@ -95,11 +95,18 @@ sealed class NumericRange[T](
 
   /** Creates a new range with the start and end values of this range and
    *  a new `step`.
+   *
+   *  @param newStep the new step value for the resulting range
    */
   def by(newStep: T): NumericRange[T] = copy(start, end, newStep)
 
 
-  /** Creates a copy of this range. */
+  /** Creates a copy of this range.
+   *
+   *  @param start the first value of the new range
+   *  @param end the upper bound of the new range (inclusive or exclusive, matching the original range)
+   *  @param step the step value between successive elements of the new range
+   */
   def copy(start: T, end: T, step: T): NumericRange[T] =
     new NumericRange(start, end, step, isInclusive)
 
@@ -350,6 +357,13 @@ object NumericRange {
   /** Calculates the number of elements in a range given start, end, step, and
    *  whether or not it is inclusive.  Throws an exception if step == 0 or
    *  the number of elements exceeds the maximum Int.
+   *
+   *  @tparam T the numeric type of the range elements, which must have an `Integral` instance
+   *  @param start the first value in the range
+   *  @param end the end boundary of the range (exclusive or inclusive depending on `isInclusive`)
+   *  @param step the increment between successive elements
+   *  @param isInclusive whether `end` is included in the range
+   *  @param num the `Integral` instance used for arithmetic on `T`
    */
   def count[T](start: T, end: T, step: T, isInclusive: Boolean)(implicit num: Integral[T]): Int = {
     val zero    = num.zero

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

@@ -160,6 +160,7 @@ sealed abstract class Range(
   /** Creates a new range with the `start` and `end` values of this range and
    *  a new `step`.
    *
+   *  @param step the new step value for the range; must be non-zero
    *  @return a new range with a different step
    */
   final def by(step: Int): Range = copy(start, end, step)
@@ -258,6 +259,9 @@ sealed abstract class Range(
   /** Creates a new range consisting of the last `n` elements of the range.
    *
    *  $doesNotUseBuilders
+   *
+   *  @param n the number of elements to take from the end of this range
+   *  @return a new range consisting of the last `n` elements, or the entire range if `n` is greater than the range length
    */
   final override def takeRight(n: Int): Range = {
     if (n <= 0) newEmptyRange(start)
@@ -274,6 +278,9 @@ sealed abstract class Range(
   /** Creates a new range consisting of the initial `length - n` elements of the range.
    *
    *  $doesNotUseBuilders
+   *
+   *  @param n the number of elements to drop from the end of this range
+   *  @return a new range consisting of all elements except the last `n`, or an empty range if `n` is greater than the range length
    */
   final override def dropRight(n: Int): Range = {
     if (n <= 0) this
@@ -536,6 +543,11 @@ object Range {
    *  precondition:  step != 0
    *  If the size of the range exceeds Int.MaxValue, the
    *  result will be negative.
+   *
+   *  @param start the first element of the range
+   *  @param end the end boundary of the range (inclusive or exclusive depending on `isInclusive`)
+   *  @param step the increment between successive elements; must be non-zero
+   *  @param isInclusive whether `end` is included in the range
    */
   def count(start: Int, end: Int, step: Int, isInclusive: Boolean): Int = {
     if (step == 0)
@@ -565,18 +577,34 @@ object Range {
 
   /** Makes a range from `start` until `end` (exclusive) with given step value.
    *  @note step != 0
+   *
+   *  @param start the first element of the range
+   *  @param end the exclusive upper bound of the range
+   *  @param step the increment between successive elements; must be non-zero
    */
   def apply(start: Int, end: Int, step: Int): Range.Exclusive = new Range.Exclusive(start, end, step)
 
-  /** Makes a range from `start` until `end` (exclusive) with step value 1. */
+  /** Makes a range from `start` until `end` (exclusive) with step value 1.
+   *
+   *  @param start the first element of the range
+   *  @param end the exclusive upper bound of the range
+   */
   def apply(start: Int, end: Int): Range.Exclusive = new Range.Exclusive(start, end, 1)
 
   /** Makes an inclusive range from `start` to `end` with given step value.
    *  @note step != 0
+   *
+   *  @param start the first element of the range
+   *  @param end the inclusive upper bound of the range
+   *  @param step the increment between successive elements; must be non-zero
    */
   def inclusive(start: Int, end: Int, step: Int): Range.Inclusive = new Range.Inclusive(start, end, step)
 
-  /** Makes an inclusive range from `start` to `end` with step value 1. */
+  /** Makes an inclusive range from `start` to `end` with step value 1.
+   *
+   *  @param start the first element of the range
+   *  @param end the inclusive upper bound of the range
+   */
   def inclusive(start: Int, end: Int): Range.Inclusive = new Range.Inclusive(start, end, 1)
 
   @SerialVersionUID(3L)

library/src/scala/collection/immutable/ArraySeq.scala

@@ -33,6 +33,8 @@ import scala.util.hashing.MurmurHash3
  *
  *  @define coll immutable array
  *  @define Coll `ArraySeq`
+ *
+ *  @tparam A the element type of the immutable array
  */
 sealed abstract class ArraySeq[+A]
   extends AbstractSeq[A]
@@ -90,7 +92,9 @@ sealed abstract class ArraySeq[+A]
 
   /** Fast concatenation of two [[ArraySeq]]s.
    *
-   *  @return null if optimisation not possible.
+   *  @tparam B the element type of the resulting sequence, a supertype of `A`
+   *  @param that the `ArraySeq` to append to this sequence
+   *  @return the concatenated `ArraySeq`, or `null` if optimization is not possible
    */
   private def appendedAllArraySeq[B >: A](that: ArraySeq[B]): ArraySeq[B] | Null = {
     // Optimise concatenation of two ArraySeqs
@@ -310,6 +314,10 @@ object ArraySeq extends StrictOptimizedClassTagSeqFactory[ArraySeq] { self =>
    *  boxed, the resulting instance is an [[ArraySeq.ofRef]]. Writing
    *  `ArraySeq.unsafeWrapArray(a.asInstanceOf[Array[Int]])` does not work, it throws a
    *  `ClassCastException` at runtime.
+   *
+   *  @tparam T the element type of the array to wrap
+   *  @param x the array to wrap, which must not be modified after wrapping
+   *  @return an `ArraySeq` backed by the given array, using the appropriate primitive specialization
    */
   def unsafeWrapArray[T](x: Array[T]): ArraySeq[T] = ((x: @unchecked) match {
     case null              => null

library/src/scala/collection/immutable/BitSet.scala

@@ -65,7 +65,11 @@ sealed abstract class BitSet
     } else this
   }
 
-  /** Updates word at index `idx`; enlarges set if `idx` outside range of set. */
+  /** Updates word at index `idx`; enlarges set if `idx` outside range of set.
+   *
+   *  @param idx the index of the word to update
+   *  @param w the new value for the word at index `idx`
+   */
   protected def updateWord(idx: Int, w: Long): BitSet
 
   override def map(f: Int => Int): BitSet = strictOptimizedMap(newSpecificBuilder, f)
@@ -108,7 +112,10 @@ object BitSet extends SpecificIterableFactory[Int, BitSet] {
 
   private def createSmall(a: Long, b: Long): BitSet = if (b == 0L) new BitSet1(a) else new BitSet2(a, b)
 
-  /** A bitset containing all the bits in an array. */
+  /** A bitset containing all the bits in an array.
+   *
+   *  @param elems the array of `Long` words representing the bits; the array is defensively copied
+   */
   def fromBitMask(elems: Array[Long]): BitSet = {
     val len = elems.length
     if (len == 0) empty
@@ -122,6 +129,8 @@ object BitSet extends SpecificIterableFactory[Int, BitSet] {
 
   /** A bitset containing all the bits in an array, wrapping the existing
    *  array without copying.
+   *
+   *  @param elems the array of `Long` words representing the bits; the caller must not modify the array after this call
    */
   def fromBitMaskNoCopy(elems: Array[Long]): BitSet = {
     val len = elems.length

library/src/scala/collection/immutable/ChampCommon.scala

@@ -105,6 +105,7 @@ private[collection] abstract class Node[T <: Node[T]] {
  *  node before traversing sub-nodes (left to right).
  *
  *  @tparam T the trie node type we are iterating over
+ *  @tparam A the element type produced by the iterator
  */
 private[immutable] abstract class ChampBaseIterator[A, T <: Node[T]] extends AbstractIterator[A] {
 
@@ -191,6 +192,7 @@ private[immutable] abstract class ChampBaseIterator[A, T <: Node[T]] extends Abs
  *  iterator performs a depth-first post-order traversal, traversing sub-nodes (right to left).
  *
  *  @tparam T the trie node type we are iterating over
+ *  @tparam A the element type produced by the iterator
  */
 private[immutable] abstract class ChampBaseReverseIterator[A, T <: Node[T]] extends AbstractIterator[A] {
 

library/src/scala/collection/immutable/HashMap.scala

@@ -274,7 +274,10 @@ final class HashMap[K, +V] private[immutable] (private[immutable] val rootNode:
 
   override def foreachEntry[U](f: (K, V) => U): Unit = rootNode.foreachEntry(f)
 
-  /** Applies a function to each key, value, and **original** hash value in this Map. */
+  /** Applies a function to each key, value, and **original** hash value in this Map.
+   *
+   *  @param f the function to apply to each key, value, and original hash triple
+   */
   @inline private[collection] def foreachWithHash(f: (K, V, Int) => Unit): Unit = rootNode.foreachWithHash(f)
 
   override def equals(that: Any): Boolean =
@@ -336,6 +339,8 @@ final class HashMap[K, +V] private[immutable] (private[immutable] val rootNode:
    *           // HashMap(2 -> 1) is returned, but it could also have returned HashMap(2 -> 3)
    *       ```
    *
+   *
+   *  @tparam V1 the value type of the resulting HashMap, a supertype of `V`
    */
   def merged[V1 >: V](that: HashMap[K, V1])(mergef: ((K, V), (K, V1)) => (K, V1)): HashMap[K, V1] =
     if (mergef == null) {
@@ -555,16 +560,18 @@ private[immutable] sealed abstract class MapNode[K, +V] extends Node[MapNode[K,
 
   /** Returns a MapNode with the passed key-value assignment added
    *
+   *  @tparam V1 the value type of the returned node, a supertype of `V`
    *  @param key the key to add to the MapNode
    *  @param value the value to associate with `key`
-   *  @param originalHash the original hash of `key`
+   *  @param originalHash the original hash code of `key` (via `key.##`)
    *  @param hash the improved hash of `key`
    *  @param shift the shift of the node (distanceFromRoot * BitPartitionSize)
    *  @param replaceValue if true, then the value currently associated to `key` will be replaced with the passed value
    *                     argument.
    *                     if false, then the key will be inserted if not already present, however if the key is present
    *                     then the passed value will not replace the current value. That is, if `false`, then this
    *                     method has `update if not exists` semantics.
+   *  @return a new `MapNode` containing the updated key-value mapping
    */
   def updated[V1 >: V](key: K, value: V1, originalHash: Int, hash: Int, shift: Int, replaceValue: Boolean): MapNode[K, V1]
 
@@ -606,17 +613,30 @@ private[immutable] sealed abstract class MapNode[K, +V] extends Node[MapNode[K,
    *
    *  `this` should be a node from `left` hashmap in `left.merged(right)(mergef)`
    *
+   *  @tparam V1 the value type of the merged result, a supertype of `V`
    *  @param that node from the "right" HashMap. Must also be at the same "path" or "position" within the right tree,
    *             as `this` is, within the left tree
+   *  @param builder the builder used to accumulate the merged key-value pairs
+   *  @param shift the bit-level offset into the hash code, equal to `depth * BitPartitionSize`
+   *  @param mergef the function used to resolve collisions between keys present in both nodes
    */
   def mergeInto[V1 >: V](that: MapNode[K, V1], builder: HashMapBuilder[K, V1], shift: Int)(mergef: ((K, V), (K, V1)) => (K, V1)): Unit
 
   /** Returns the exact (equal by reference) key, and value, associated to a given key.
    *  If the key is not bound to a value, then an exception is thrown
+   *
+   *  @param key the key to look up
+   *  @param originalHash the original hash code of `key` (via `key.##`)
+   *  @param hash the improved hash of `key`
+   *  @param shift the bit-level offset into the hash code, equal to `depth * BitPartitionSize`
    */
   def getTuple(key: K, originalHash: Int, hash: Int, shift: Int): (K, V)
 
-  /** Adds all key-value pairs to a builder. */
+  /** Adds all key-value pairs to a builder.
+   *
+   *  @tparam V1 the value type of the target builder, a supertype of `V`
+   *  @param builder the builder to add the key-value pairs to
+   */
   def buildTo[V1 >: V](builder: HashMapBuilder[K, V1]): Unit
 }
 
@@ -784,13 +804,15 @@ private final class BitmapIndexedMapNode[K, +V](
    *  If instead this method may not mutate the child node in which the to-be-updated key-value pair belongs, then
    *  that child will be updated immutably, but the result will be mutably re-inserted as a child of this node.
    *
+   *  @tparam V1 the value type of the updated node, a supertype of `V`
    *  @param key the key to update
    *  @param value the value to set `key` to
    *  @param originalHash key.##
    *  @param keyHash the improved hash
+   *
    *  @param shallowlyMutableNodeMap bitmap of child nodes of this node, which can be shallowly mutated
    *                                during the call to this method
-   *
+   *  @param shift the bit-level offset into the hash code, equal to `depth * BitPartitionSize`
    *  @return Int which is the bitwise OR of shallowlyMutableNodeMap and any freshly created nodes, which will be
    *         available for mutations in subsequent calls.
    */
@@ -1023,6 +1045,7 @@ private final class BitmapIndexedMapNode[K, +V](
 
   /** Variant of `copyAndMigrateFromInlineToNode` which mutates `this` rather than returning a new node.
    *
+   *  @tparam V1 the value type of the child node, a supertype of `V`
    *  @param bitpos the bit position of the data to migrate to node
    *  @param keyHash the improved hash of the key currently at `bitpos`
    *  @param node the node to place at `bitpos` beneath `this`
@@ -2171,9 +2194,17 @@ private final class MapKeyValueTupleHashIterator[K, V](rootNode: MapNode[K, V])
   }
 }
 
-/** Used in HashMap[K, V]#removeAll(HashSet[K]). */
+/** Used in HashMap[K, V]#removeAll(HashSet[K]).
+ *
+ *  @tparam K the key type
+ *  @param rootSetNode the root node of the `HashSet` whose keys are to be removed
+ */
 private final class MapNodeRemoveAllSetNodeIterator[K](rootSetNode: SetNode[K]) extends ChampBaseIterator[K, SetNode[K]](rootSetNode) {
-  /** Returns the result of immutably removing all keys in `rootSetNode` from `rootMapNode`. */
+  /** Returns the result of immutably removing all keys in `rootSetNode` from `rootMapNode`.
+   *
+   *  @tparam V the value type of the map node
+   *  @param rootMapNode the root node of the map from which keys will be removed
+   */
   def removeAll[V](rootMapNode: BitmapIndexedMapNode[K, V]): BitmapIndexedMapNode[K, V] = {
     var curr = rootMapNode
     while (curr.size > 0 && hasNext) {
@@ -2214,13 +2245,19 @@ object HashMap extends MapFactory[HashMap] {
 
   /** Creates a new Builder which can be reused after calling `result()` without an
    *  intermediate call to `clear()` in order to build multiple related results.
+   *
+   *  @tparam K the key type of the HashMap
+   *  @tparam V the value type of the HashMap
    */
   def newBuilder[K, V]: ReusableBuilder[(K, V), HashMap[K, V]] = new HashMapBuilder[K, V]
 }
 
 
 /** A `Builder` for a `HashMap`.
  *  $multipleResults
+ *
+ *  @tparam K the key type of the HashMap being built
+ *  @tparam V the value type of the HashMap being built
  */
 private[immutable] final class HashMapBuilder[K, V] extends ReusableBuilder[(K, V), HashMap[K, V]] {
   import MapNode._
@@ -2247,7 +2284,12 @@ private[immutable] final class HashMapBuilder[K, V] extends ReusableBuilder[(K,
       rootNode.getOrElse(key, originalHash, improve(originalHash), 0, value)
     }
 
-  /** Inserts element `elem` into array `as` at index `ix`, shifting right the trailing elems. */
+  /** Inserts element `elem` into array `as` at index `ix`, shifting right the trailing elems.
+   *
+   *  @param as the source array to insert into
+   *  @param ix the zero-based index at which to insert `elem`
+   *  @param elem the element to insert
+   */
   private def insertElement(as: Array[Int], ix: Int, elem: Int): Array[Int] = {
     if (ix < 0) throw new ArrayIndexOutOfBoundsException
     if (ix > as.length) throw new ArrayIndexOutOfBoundsException
@@ -2258,7 +2300,16 @@ private[immutable] final class HashMapBuilder[K, V] extends ReusableBuilder[(K,
     result
   }
 
-  /** Inserts key-value into the bitmapIndexMapNode. Requires that this is a new key-value pair. */
+  /** Inserts key-value into the bitmapIndexMapNode. Requires that this is a new key-value pair.
+   *
+   *  @tparam V1 the value type being inserted, a supertype of `V`
+   *  @param bm the bitmap-indexed map node to mutate
+   *  @param bitpos the bit position in the bitmap where the key-value pair should be inserted
+   *  @param key the key to insert
+   *  @param originalHash the original hash code of `key` (via `key.##`)
+   *  @param keyHash the improved hash of `key`
+   *  @param value the value to associate with `key`
+   */
   private def insertValue[V1 >: V](bm: BitmapIndexedMapNode[K, V],bitpos: Int, key: K, originalHash: Int, keyHash: Int, value: V1): Unit = {
     val dataIx = bm.dataIndex(bitpos)
     val idx = TupleLength * dataIx
@@ -2281,7 +2332,15 @@ private[immutable] final class HashMapBuilder[K, V] extends ReusableBuilder[(K,
     bm.cachedJavaKeySetHashCode += keyHash
   }
 
-  /** Upserts a key/value pair into mapNode, mutably. */
+  /** Upserts a key/value pair into mapNode, mutably.
+   *
+   *  @param mapNode the map node to update in place
+   *  @param key the key to insert or update
+   *  @param value the value to associate with `key`
+   *  @param originalHash the original hash code of `key` (via `key.##`)
+   *  @param keyHash the improved hash of `key`
+   *  @param shift the bit-level offset into the hash code, equal to `depth * BitPartitionSize`
+   */
   private[immutable] def update(mapNode: MapNode[K, V], key: K, value: V, originalHash: Int, keyHash: Int, shift: Int): Unit = {
     mapNode match {
       case bm: BitmapIndexedMapNode[K, V] =>