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

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

@@ -97,15 +97,17 @@ sealed class NumericRange[T](
    *  a new `step`.
    *
    *  @param newStep the new step value for the resulting range
+   *  @return a new `NumericRange` with the same `start` and `end` as this range but with `newStep` as its step
    */
   def by(newStep: T): NumericRange[T] = copy(start, end, newStep)
 
 
   /** 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 end the end boundary of the new range (inclusive or exclusive, matching this range)
    *  @param step the step value between successive elements of the new range
+   *  @return a new `NumericRange` with the given `start`, `end`, and `step`, preserving this range's inclusivity
    */
   def copy(start: T, end: T, step: T): NumericRange[T] =
     new NumericRange(start, end, step, isInclusive)
@@ -364,6 +366,7 @@ object NumericRange {
    *  @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`
+   *  @return the number of elements in the range
    */
   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

@@ -548,6 +548,7 @@ object 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
+   *  @return the number of elements in the range, or `-1` if the count exceeds `Int.MaxValue`
    */
   def count(start: Int, end: Int, step: Int, isInclusive: Boolean): Int = {
     if (step == 0)
@@ -581,13 +582,15 @@ object Range {
    *  @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
+   *  @return an exclusive `Range` from `start` to `end` stepping by `step`
    */
   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.
    *
    *  @param start the first element of the range
    *  @param end the exclusive upper bound of the range
+   *  @return an exclusive `Range` from `start` to `end` with step `1`
    */
   def apply(start: Int, end: Int): Range.Exclusive = new Range.Exclusive(start, end, 1)
 
@@ -597,13 +600,15 @@ object Range {
    *  @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
+   *  @return an inclusive `Range` from `start` to `end` stepping by `step`
    */
   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.
    *
    *  @param start the first element of the range
    *  @param end the inclusive upper bound of the range
+   *  @return an inclusive `Range` from `start` to `end` with step `1`
    */
   def inclusive(start: Int, end: Int): Range.Inclusive = new Range.Inclusive(start, end, 1)
 

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

@@ -69,6 +69,7 @@ sealed abstract class BitSet
    *
    *  @param idx the index of the word to update
    *  @param w the new value for the word at index `idx`
+   *  @return a new bitset with the word at `idx` set to `w`, growing the underlying storage if needed
    */
   protected def updateWord(idx: Int, w: Long): BitSet
 
@@ -115,6 +116,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; the array is defensively copied
+   *  @return a new immutable bitset containing the bits represented by `elems`
    */
   def fromBitMask(elems: Array[Long]): BitSet = {
     val len = elems.length
@@ -131,6 +133,7 @@ object BitSet extends SpecificIterableFactory[Int, BitSet] {
    *  array without copying.
    *
    *  @param elems the array of `Long` words representing the bits; the caller must not modify the array after this call
+   *  @return a new immutable bitset backed by the given `elems` array
    */
   def fromBitMaskNoCopy(elems: Array[Long]): BitSet = {
     val len = elems.length

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

@@ -341,6 +341,8 @@ final class HashMap[K, +V] private[immutable] (private[immutable] val rootNode:
    *
    *
    *  @tparam V1 the value type of the resulting HashMap, a supertype of `V`
+   *
+   *  @return a new `HashMap` containing all key-value pairs from both maps, with `mergef` applied to resolve collisions when non-null
    */
   def merged[V1 >: V](that: HashMap[K, V1])(mergef: ((K, V), (K, V1)) => (K, V1)): HashMap[K, V1] =
     if (mergef == null) {
@@ -629,6 +631,7 @@ private[immutable] sealed abstract class MapNode[K, +V] extends Node[MapNode[K,
    *  @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`
+   *  @return the `(key, value)` tuple bound to `key` in this node
    */
   def getTuple(key: K, originalHash: Int, hash: Int, shift: Int): (K, V)
 
@@ -1049,6 +1052,7 @@ private final class BitmapIndexedMapNode[K, +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`
+   *  @return `this`, after mutating it so that `node` replaces the inline data at `bitpos`
    */
   def migrateFromInlineToNodeInPlace[V1 >: V](bitpos: Int, keyHash: Int, node: MapNode[K, V1]): this.type = {
     val dataIx = dataIndex(bitpos)
@@ -2204,6 +2208,7 @@ private final class MapNodeRemoveAllSetNodeIterator[K](rootSetNode: SetNode[K])
    *
    *  @tparam V the value type of the map node
    *  @param rootMapNode the root node of the map from which keys will be removed
+   *  @return the root node of a map with every key from `rootSetNode` removed from `rootMapNode`
    */
   def removeAll[V](rootMapNode: BitmapIndexedMapNode[K, V]): BitmapIndexedMapNode[K, V] = {
     var curr = rootMapNode
@@ -2248,6 +2253,7 @@ object HashMap extends MapFactory[HashMap] {
    *
    *  @tparam K the key type of the HashMap
    *  @tparam V the value type of the HashMap
+   *  @return a fresh `ReusableBuilder` that constructs `HashMap[K, V]` instances and can be reused across multiple results
    */
   def newBuilder[K, V]: ReusableBuilder[(K, V), HashMap[K, V]] = new HashMapBuilder[K, V]
 }
@@ -2289,6 +2295,7 @@ private[immutable] final class HashMapBuilder[K, V] extends ReusableBuilder[(K,
    *  @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
+   *  @return a new array of length `as.length + 1` containing the elements of `as` with `elem` inserted at index `ix`
    */
   private def insertElement(as: Array[Int], ix: Int, elem: Int): Array[Int] = {
     if (ix < 0) throw new ArrayIndexOutOfBoundsException

library/src/scala/collection/immutable/HashSet.scala

@@ -1968,6 +1968,7 @@ object HashSet extends IterableFactory[HashSet] {
    *  intermediate call to `clear()` in order to build multiple related results.
    *
    *  @tparam A the element type of the set to build
+   *  @return a new reusable builder that produces a `HashSet[A]`
    */
   def newBuilder[A]: ReusableBuilder[A, HashSet[A]] = new HashSetBuilder
 }
@@ -2000,6 +2001,7 @@ private[collection] final class HashSetBuilder[A] extends ReusableBuilder[A, Has
    *  @param as the source array to insert into
    *  @param ix the index at which to insert the element
    *  @param elem the element to insert
+   *  @return a new array of length `as.length + 1` with `elem` inserted at index `ix`
    */
   private def insertElement(as: Array[Int], ix: Int, elem: Int): Array[Int] = {
     if (ix < 0) throw new ArrayIndexOutOfBoundsException

library/src/scala/collection/immutable/IntMap.scala

@@ -129,6 +129,7 @@ private[immutable] abstract class IntMapIterator[V, T](it: IntMap[V]) extends Ab
   /** What value do we assign to a tip?
    *
    *  @param tip the leaf node to extract a value from
+   *  @return the iterator element derived from `tip` (e.g. the key, the value, or the key/value pair, as determined by the concrete subclass)
    */
   def valueOf(tip: IntMap.Tip[V]): T