diff --git a/library/src/scala/collection/ArrayOps.scala b/library/src/scala/collection/ArrayOps.scala index 5706d49bebd5..6174fceb6a5f 100644 --- a/library/src/scala/collection/ArrayOps.scala +++ b/library/src/scala/collection/ArrayOps.scala @@ -130,6 +130,7 @@ object ArrayOps { /** Creates a new non-strict filter which combines this filter with the given predicate. * * @param q the additional predicate to apply in conjunction with `p` + * @return a new `WithFilter` that retains only elements satisfying both `p` and `q` */ def withFilter(q: A => Boolean): WithFilter[A]^{this, q} = new WithFilter[A](a => p(a) && q(a), xs) } @@ -392,24 +393,28 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { /** An array containing the first `n` elements of this array. * * @param n the number of elements to take from this array + * @return a new array containing the first `n` elements of this array, all elements if `n` exceeds the array length, or an empty array if `n` is non-positive */ def take(n: Int): Array[A] = slice(0, n) /** The rest of the array without its `n` first elements. * * @param n the number of elements to drop from the front of this array + * @return a new array containing all elements of this array except the first `n`, an empty array if `n` exceeds the array length, or a copy of all elements if `n` is non-positive */ def drop(n: Int): Array[A] = slice(n, xs.length) /** An array containing the last `n` elements of this array. * * @param n the number of elements to take from the end of this array + * @return a new array containing the last `n` elements of this array, or all elements if `n` exceeds the array length */ def takeRight(n: Int): Array[A] = drop(xs.length - max(n, 0)) /** The rest of the array without its `n` last elements. * * @param n the number of elements to drop from the end of this array + * @return a new array containing all elements of this array except the last `n`, or empty if `n` exceeds the array length */ def dropRight(n: Int): Array[A] = take(xs.length - max(n, 0)) @@ -507,6 +512,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { /** A pair of, first, all elements that satisfy predicate `p` and, second, all elements that do not. * * @param p the predicate used to partition the elements + * @return a pair of arrays: the first containing all elements that satisfy `p`, the second containing all elements that do not */ def partition(p: A => Boolean): (Array[A], Array[A]) = { val res1, res2 = ArrayBuilder.make[A] @@ -1070,6 +1076,8 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * partial function to it. * * @tparam B the result type of the partial function + * @param pf the partial function applied to the first element on which it is defined + * @return a `Some` containing `pf` applied to the first element on which it is defined, or `None` if no such element exists */ def collectFirst[B](@deprecatedName("f","2.13.9") pf: PartialFunction[A, B]^): Option[B] = { val fallback: Any => Any = ArrayOps.fallback @@ -1178,6 +1186,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * * @tparam B the element type of the returned array, a supertype of `A` * @param x the element to append + * @return a new array consisting of all elements of this array followed by `x` */ def appended[B >: A : ClassTag](x: B): Array[B] = { val dest = Array.copyAs[B](xs, xs.length+1) @@ -1191,6 +1200,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * * @tparam B the element type of the returned array, a supertype of `A` * @param x the element to prepend + * @return a new array consisting of `x` followed by all elements of this array */ def prepended[B >: A : ClassTag](x: B): Array[B] = { val dest = new Array[B](xs.length + 1) @@ -1205,6 +1215,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * * @tparam B the element type of the returned array, a supertype of `A` * @param prefix the collection to prepend + * @return a new array consisting of all elements of `prefix` followed by all elements of this array */ def prependedAll[B >: A : ClassTag](prefix: IterableOnce[B]^): Array[B] = { val b = ArrayBuilder.make[B] @@ -1220,6 +1231,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * * @tparam B the element type of the returned array, a supertype of `A` * @param prefix the array to prepend + * @return a new array consisting of all elements of `prefix` followed by all elements of this array */ def prependedAll[B >: A : ClassTag](prefix: Array[? <: B]): Array[B] = { val dest = Array.copyAs[B](prefix, prefix.length+xs.length) @@ -1235,6 +1247,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * * @tparam B the element type of the returned array, a supertype of `A` * @param suffix the collection to append + * @return a new array consisting of all elements of this array followed by all elements of `suffix` */ def appendedAll[B >: A : ClassTag](suffix: IterableOnce[B]^): Array[B] = { val b = ArrayBuilder.make[B] @@ -1248,6 +1261,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * * @tparam B the element type of the returned array, a supertype of `A` * @param suffix the array to append + * @return a new array consisting of all elements of this array followed by all elements of `suffix` */ def appendedAll[B >: A : ClassTag](suffix: Array[? <: B]): Array[B] = { val dest = Array.copyAs[B](xs, xs.length+suffix.length) @@ -1284,6 +1298,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * @param from The start index from which to patch * @param other The patch values * @param replaced The number of values in the original array that are replaced by the patch. + * @return a new array consisting of the elements of this array with `replaced` elements starting at `from` replaced by the elements of `other` (subject to the edge cases noted above) */ def patch[B >: A : ClassTag](from: Int, other: IterableOnce[B]^, replaced: Int): Array[B] = { val b = ArrayBuilder.make[B] @@ -1514,6 +1529,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * * @tparam B the type of the elements of the array. * @param xs the array to fill. + * @return the number of elements actually copied */ def copyToArray[B >: A](xs: Array[B]): Int = copyToArray(xs, 0) @@ -1525,6 +1541,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * @tparam B the type of the elements of the array. * @param xs the array to fill. * @param start the starting index within the destination array. + * @return the number of elements actually copied */ def copyToArray[B >: A](xs: Array[B], start: Int): Int = copyToArray(xs, start, Int.MaxValue) @@ -1537,6 +1554,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * @param xs the array to fill. * @param start the starting index within the destination array. * @param len the maximal number of elements to copy. + * @return the number of elements actually copied */ def copyToArray[B >: A](xs: Array[B], start: Int, len: Int): Int = { val copied = IterableOnce.elemsToCopyToArray(this.xs.length, xs.length, start, len) @@ -1549,6 +1567,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { /** Creates a copy of this array with the specified element type. * * @tparam B the element type of the copy, a supertype of `A` + * @return a new `Array[B]` containing all elements of this array */ def toArray[B >: A: ClassTag]: Array[B] = { val destination = new Array[B](xs.length) @@ -1560,6 +1579,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { /** Counts the number of elements in this array which satisfy a predicate. * * @param p the predicate used to test elements + * @return the number of elements of this array for which `p` returns `true` */ def count(p: A => Boolean): Int = { var i, res = 0 @@ -1576,6 +1596,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal { * * @tparam B the element type of the prefix array, a supertype of `A` * @param that the array to test as a prefix + * @return `true` if this array has `that` as a prefix, `false` otherwise */ @`inline` def startsWith[B >: A](that: Array[B]): Boolean = startsWith(that, 0) diff --git a/library/src/scala/collection/BitSet.scala b/library/src/scala/collection/BitSet.scala index 9d0e8b77027b..ef113a2cfa61 100644 --- a/library/src/scala/collection/BitSet.scala +++ b/library/src/scala/collection/BitSet.scala @@ -105,12 +105,14 @@ transparent trait BitSetOps[+C <: BitSet & BitSetOps[C]] * **Note:** requires `idx >= 0` * * @param idx the index of the word to retrieve, must be non-negative + * @return the 64-bit word at position `idx`, or `0L` if `idx` is outside the range of the set */ protected[collection] def word(idx: Int): Long /** Creates a new set of this kind from an array of longs * * @param elems the array of 64-bit words representing the bit mask for the new set + * @return a new bitset of type `C` whose contents are given by the bit mask in `elems` (the array is used directly and not copied) */ protected[collection] def fromBitMaskNoCopy(elems: Array[Long]): C diff --git a/library/src/scala/collection/BuildFrom.scala b/library/src/scala/collection/BuildFrom.scala index 1ca9c4659f99..589a171888f0 100644 --- a/library/src/scala/collection/BuildFrom.scala +++ b/library/src/scala/collection/BuildFrom.scala @@ -36,6 +36,7 @@ trait BuildFrom[-From, -A, +C] extends Any { self: BuildFrom[From, A, C] => * Building collections with `fromSpecific` is preferred because it can be lazy for lazy collections. * * @param from the source collection providing the factory for creating the builder + * @return a new `Builder` that accepts elements of type `A` and produces a collection of type `C` */ def newBuilder(from: From): Builder[A, C] @@ -45,6 +46,7 @@ trait BuildFrom[-From, -A, +C] extends Any { self: BuildFrom[From, A, C] => /** Partially apply a BuildFrom to a Factory. * * @param from the source collection to partially apply, producing a `Factory` bound to it + * @return a `Factory` that builds collections of type `C` from elements of type `A`, using `from` as the source collection */ def toFactory(from: From): Factory[A, C] = new Factory[A, C] { def fromSpecific(it: IterableOnce[A]^): C^{it} = self.fromSpecific(from)(it) @@ -57,6 +59,11 @@ object BuildFrom extends BuildFromLowPriority1 { /** Builds the source collection type from a MapOps. * * @tparam CC the higher-kinded type constructor of the map collection (e.g. `HashMap`) + * @tparam K0 the key type of the source map + * @tparam V0 the value type of the source map + * @tparam K the key type of the resulting map + * @tparam V the value type of the resulting map + * @return a `BuildFrom` instance that builds a `CC[K, V]` from `(K, V)` pairs, using the `mapFactory` of the source `CC[K0, V0]` */ implicit def buildFromMapOps[CC[X, Y] <: Map[X, Y] & MapOps[X, Y, CC, ?], K0, V0, K, V]: BuildFrom[CC[K0, V0] & Map[K0, V0], (K, V), CC[K, V] & Map[K, V]] = new BuildFrom[CC[K0, V0], (K, V), CC[K, V]] { //TODO: Reuse a prototype instance @@ -67,6 +74,11 @@ object BuildFrom extends BuildFromLowPriority1 { /** Builds the source collection type from a SortedMapOps. * * @tparam CC the higher-kinded type constructor of the sorted map collection (e.g. `TreeMap`) + * @tparam K0 the key type of the source sorted map + * @tparam V0 the value type of the source sorted map + * @tparam K the key type of the resulting sorted map, which must have an `Ordering` + * @tparam V the value type of the resulting sorted map + * @return a `BuildFrom` instance that builds a `CC[K, V]` from `(K, V)` pairs, using the `sortedMapFactory` of the source `CC[K0, V0]` */ implicit def buildFromSortedMapOps[CC[X, Y] <: SortedMap[X, Y] & SortedMapOps[X, Y, CC, ?], K0, V0, K : Ordering, V]: BuildFrom[CC[K0, V0] & SortedMap[K0, V0], (K, V), CC[K, V] & SortedMap[K, V]] = new BuildFrom[CC[K0, V0], (K, V), CC[K, V]] { def newBuilder(from: CC[K0, V0]): Builder[(K, V), CC[K, V]] = (from: SortedMapOps[K0, V0, CC, ?]).sortedMapFactory.newBuilder[K, V] @@ -112,6 +124,9 @@ trait BuildFromLowPriority1 extends BuildFromLowPriority2 { /** Builds the source collection type from an Iterable with SortedOps. * * @tparam CC the higher-kinded type constructor of the sorted set collection (e.g. `TreeSet`) + * @tparam A0 the element type of the source sorted set + * @tparam A the element type of the resulting sorted set, which must have an `Ordering` + * @return a `BuildFrom` instance that builds a sorted `CC[A]` (requiring an `Ordering[A]`) from elements of type `A`, using the `sortedIterableFactory` of the source `CC[A0]` */ // Restating the upper bound of CC in the result type seems redundant, but it serves to prune the // implicit search space for faster compilation and reduced change of divergence. See the compilation @@ -132,6 +147,9 @@ trait BuildFromLowPriority2 { /** Builds the source collection type from an IterableOps. * * @tparam CC the higher-kinded type constructor of the iterable collection (e.g. `List`, `Vector`) + * @tparam A0 the element type of the source iterable + * @tparam A the element type of the resulting iterable + * @return a `BuildFrom` instance that builds a `CC[A]` from elements of type `A`, using the `iterableFactory` of the source `CC[A0]` */ implicit def buildFromIterableOps[CC[X] <: Iterable[X] & IterableOps[X, CC, ?], A0, A]: BuildFrom[CC[A0], A, CC[A]] = new BuildFrom[CC[A0], A, CC[A]] { //TODO: Reuse a prototype instance diff --git a/library/src/scala/collection/Factory.scala b/library/src/scala/collection/Factory.scala index 382a5025f3e0..f687a5c9e0b0 100644 --- a/library/src/scala/collection/Factory.scala +++ b/library/src/scala/collection/Factory.scala @@ -93,7 +93,9 @@ trait IterableFactory[+CC[_]] extends Serializable, caps.Pure { def from[A](source: IterableOnce[A]^): CC[A]^{source} /** An empty $coll. + * * @tparam A the type of the ${coll}'s elements + * @return an empty $coll of type `CC[A]` */ def empty[A]: CC[A] @@ -415,6 +417,7 @@ trait MapFactory[+CC[_, _]] extends Serializable { self: MapFactory[CC] => * * @tparam K the type of the keys * @tparam V the type of the values + * @return an empty map of type `CC[K, V]` */ def empty[K, V]: CC[K, V] @@ -423,6 +426,7 @@ trait MapFactory[+CC[_, _]] extends Serializable { self: MapFactory[CC] => * @tparam K the type of the keys * @tparam V the type of the values * @param it the source collection of key-value pairs + * @return a new map of type `CC[K, V]` containing the bindings from `it` */ def from[K, V](it: IterableOnce[(K, V)]^): CC[K, V]^{it} @@ -431,6 +435,7 @@ trait MapFactory[+CC[_, _]] extends Serializable { self: MapFactory[CC] => * @tparam K the type of the keys * @tparam V the type of the values * @param elems the key-value pairs to include in the map + * @return a new map of type `CC[K, V]` containing the given `elems` */ def apply[K, V](elems: (K, V)*): CC[K, V] = from(elems) @@ -438,6 +443,7 @@ trait MapFactory[+CC[_, _]] extends Serializable { self: MapFactory[CC] => * * @tparam K the type of the keys * @tparam V the type of the values + * @return a new `Builder` that accepts key-value pairs and produces a `CC[K, V]` */ def newBuilder[K, V]: Builder[(K, V), CC[K, V]] @@ -445,6 +451,7 @@ trait MapFactory[+CC[_, _]] extends Serializable { self: MapFactory[CC] => * * @tparam K the type of the keys * @tparam V the type of the values + * @return a `Factory` that builds a `CC[K, V]` from a collection of key-value pairs */ implicit def mapFactory[K, V]: Factory[(K, V), CC[K, V]] = MapFactory.toFactory(this) } diff --git a/library/src/scala/collection/IndexedSeq.scala b/library/src/scala/collection/IndexedSeq.scala index ff31b03267cb..3ec9f8968c53 100644 --- a/library/src/scala/collection/IndexedSeq.scala +++ b/library/src/scala/collection/IndexedSeq.scala @@ -167,6 +167,10 @@ transparent trait IndexedSeqOps[+A, +CC[_], +C] extends Any with SeqOps[A, CC, C * * @tparam A the element type of the sequence * @tparam CC the type constructor for the resulting collection (e.g., `IndexedSeq`) + * @tparam C the type of the concrete collection being sliced + * @param s the underlying indexed sequence from which slices are produced + * @param size the number of elements in each slice; must be positive + * @param step the distance between the starting positions of successive slices; must be positive */ private final class IndexedSeqSlidingIterator[A, CC[_], C](s: IndexedSeqOps[A, CC, C]^, size: Int, step: Int) extends AbstractIterator[C^{s}] { diff --git a/library/src/scala/collection/Iterable.scala b/library/src/scala/collection/Iterable.scala index bc30faee5bdc..9f85b9a5f8d4 100644 --- a/library/src/scala/collection/Iterable.scala +++ b/library/src/scala/collection/Iterable.scala @@ -642,6 +642,7 @@ transparent trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] w * @param key the discriminator function * @param f the element transformation function * @param reduce the reduction function used to combine values mapped to the same key + * @return a map associating each key `k` produced by `key` with the reduction of all values produced by applying `f` to elements that map to `k` */ def groupMapReduce[K, B](key: A => K)(f: A => B)(reduce: (B, B) => B): immutable.Map[K, B] = { val m = mutable.Map.empty[K, B] diff --git a/library/src/scala/collection/IterableOnce.scala b/library/src/scala/collection/IterableOnce.scala index d23631ba62f3..15f37050ba48 100644 --- a/library/src/scala/collection/IterableOnce.scala +++ b/library/src/scala/collection/IterableOnce.scala @@ -81,6 +81,8 @@ trait IterableOnce[+A] extends Any { this: IterableOnce[A]^ => * streams. * * @tparam S the type of the returned `Stepper`, determined by the implicit `StepperShape` + * @param shape the `StepperShape` that determines the concrete `Stepper` subtype to return + * @return a `Stepper` over the elements of this $coll, using a primitive-typed `Stepper` subclass for `Int`/`Long`/`Double` (and related) element types */ def stepper[S <: Stepper[?]](implicit shape: StepperShape[A, S]): S^{this} = { import convert.impl._ @@ -345,6 +347,7 @@ object IterableOnce { * * @tparam A the element type of the collection * @tparam CC the type constructor for the collection's "same element type" results (e.g., `List` for `List[Int]`) + * @tparam C the concrete collection type returned by operations that preserve it (e.g., `List[Int]` when `CC` is `List`) */ transparent trait IterableOnceOps[+A, +CC[_], +C] extends Any { this: IterableOnce[A]^ => /////////////////////////////////////////////////////////////// Abstract methods that must be implemented diff --git a/library/src/scala/collection/Iterator.scala b/library/src/scala/collection/Iterator.scala index a5cbe06e850d..3ecac0787c02 100644 --- a/library/src/scala/collection/Iterator.scala +++ b/library/src/scala/collection/Iterator.scala @@ -358,6 +358,10 @@ trait Iterator[+A] extends IterableOnce[A] with IterableOnceOps[A, Iterator, Ite * * @tparam B the element type of the sequences produced by the grouped iterator, a supertype of `A` * @param size the number of elements per group + * @return a `GroupedIterator` producing `Seq[B]`s of size `size`, except the + * last segment (which may be the only segment) will be truncated + * if there are fewer than `size` elements remaining to be grouped. + * The truncation behavior can be overridden via `withPartial` or `withPadding`. */ def grouped[B >: A](size: Int): GroupedIterator[B]^{this} = new GroupedIterator[B](self, size, size) @@ -709,6 +713,9 @@ trait Iterator[+A] extends IterableOnce[A] with IterableOnceOps[A, Iterator, Ite * @note Reuse: $consumesOneAndProducesTwoIterators * * @param p the predicate used to partition elements into the leading and trailing iterators + * @return a pair of iterators: the longest prefix of this iterator whose + * elements all satisfy `p`, and the remainder of this iterator + * starting with the first element that does not satisfy `p` */ def span(p: A => Boolean): (Iterator[A]^{this, p}, Iterator[A]^{this, p}) = { /* @@ -815,6 +822,9 @@ trait Iterator[+A] extends IterableOnce[A] with IterableOnceOps[A, Iterator, Ite * * @param from the index of the first element in the slice * @param until the index of the first element following the slice, or negative for unbounded + * @return an iterator producing the elements of this iterator from index + * `from` (inclusive) up to index `until` (exclusive), or to the end + * of this iterator if `until` is negative */ protected def sliceIterator(from: Int, until: Int): Iterator[A]^{this} = { val lo = from max 0 @@ -935,6 +945,8 @@ trait Iterator[+A] extends IterableOnce[A] with IterableOnceOps[A, Iterator, Ite * @param from The start index from which to patch * @param patchElems The iterator of patch values * @param replaced The number of values in the original iterator that are replaced by the patch. + * @return an iterator that yields the elements of this iterator with `replaced` + * elements starting at position `from` substituted by the elements of `patchElems` * @note Reuse: $consumesTwoAndProducesOneIterator */ def patch[B >: A](from: Int, patchElems: Iterator[B]^, replaced: Int): Iterator[B]^{this, patchElems} = @@ -1024,6 +1036,8 @@ object Iterator extends IterableFactory[Iterator] { /** The iterator which produces no values. * * @tparam T the element type of the empty iterator + * @return an iterator that produces no values, whose `hasNext` always + * returns `false` and whose `next()` always throws `NoSuchElementException` */ @`inline` final def empty[T]: Iterator[T] = _empty @@ -1334,6 +1348,9 @@ object Iterator extends IterableFactory[Iterator] { * @tparam A the element type produced by the iterator * @tparam S the type of the internal state * @param init the initial state value + * @param f a function that, given the current state, returns `Some((nextElement, nextState))` + * to produce the next element and updated state, or `None` to signal + * the end of the iteration */ private final class UnfoldIterator[A, S](init: S)(f: S => Option[(A, S)]) extends AbstractIterator[A] { private var state: S = init diff --git a/library/src/scala/collection/JavaConverters.scala b/library/src/scala/collection/JavaConverters.scala index baa5173c3ef7..941b78c6c5de 100644 --- a/library/src/scala/collection/JavaConverters.scala +++ b/library/src/scala/collection/JavaConverters.scala @@ -147,6 +147,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the iterator * @param i the Scala `Iterator` to be converted + * @return an adapter exposing an `asJava` method that returns the corresponding Java `Iterator` */ implicit def asJavaIteratorConverter[A](i : Iterator[A]): AsJava[ju.Iterator[A]] = new AsJava(asJavaIterator(i)) @@ -156,6 +157,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the iterator * @param i the Scala `Iterator` to be converted + * @return an adapter exposing an `asJavaEnumeration` method that returns the corresponding Java `Enumeration` */ implicit def asJavaEnumerationConverter[A](i : Iterator[A]): AsJavaEnumeration[A] = new AsJavaEnumeration(i) @@ -165,6 +167,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the iterable * @param i the Scala `Iterable` to be converted + * @return an adapter exposing an `asJava` method that returns the corresponding Java `Iterable` */ implicit def asJavaIterableConverter[A](i : Iterable[A]): AsJava[jl.Iterable[A]] = new AsJava(asJavaIterable(i)) @@ -174,6 +177,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the iterable * @param i the Scala `Iterable` to be converted + * @return an adapter exposing an `asJavaCollection` method that returns the corresponding immutable Java `Collection` */ implicit def asJavaCollectionConverter[A](i : Iterable[A]): AsJavaCollection[A] = new AsJavaCollection(i) @@ -183,6 +187,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the buffer * @param b the Scala mutable `Buffer` to be converted + * @return an adapter exposing an `asJava` method that returns the corresponding Java `List` */ implicit def bufferAsJavaListConverter[A](b : mutable.Buffer[A]): AsJava[ju.List[A]] = new AsJava(bufferAsJavaList(b)) @@ -192,6 +197,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the sequence * @param b the Scala mutable `Seq` to be converted + * @return an adapter exposing an `asJava` method that returns the corresponding Java `List` */ implicit def mutableSeqAsJavaListConverter[A](b : mutable.Seq[A]): AsJava[ju.List[A]] = new AsJava(mutableSeqAsJavaList(b)) @@ -201,6 +207,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the sequence * @param b the Scala `Seq` to be converted + * @return an adapter exposing an `asJava` method that returns the corresponding Java `List` */ implicit def seqAsJavaListConverter[A](b : Seq[A]): AsJava[ju.List[A]] = new AsJava(seqAsJavaList(b)) @@ -210,6 +217,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the set * @param s the Scala mutable `Set` to be converted + * @return an adapter exposing an `asJava` method that returns the corresponding Java `Set` */ implicit def mutableSetAsJavaSetConverter[A](s : mutable.Set[A]): AsJava[ju.Set[A]] = new AsJava(mutableSetAsJavaSet(s)) @@ -219,6 +227,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the set * @param s the Scala `Set` to be converted + * @return an adapter exposing an `asJava` method that returns the corresponding Java `Set` */ implicit def setAsJavaSetConverter[A](s : Set[A]): AsJava[ju.Set[A]] = new AsJava(setAsJavaSet(s)) @@ -229,6 +238,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * @tparam K the type of the map keys * @tparam V the type of the map values * @param m the Scala mutable `Map` to be converted + * @return an adapter exposing an `asJava` method that returns the corresponding Java `Map` */ implicit def mutableMapAsJavaMapConverter[K, V](m : mutable.Map[K, V]): AsJava[ju.Map[K, V]] = new AsJava(mutableMapAsJavaMap(m)) @@ -239,6 +249,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * @tparam K the type of the map keys * @tparam V the type of the map values * @param m the Scala mutable `Map` to be converted + * @return an adapter exposing an `asJavaDictionary` method that returns the corresponding Java `Dictionary` */ implicit def asJavaDictionaryConverter[K, V](m : mutable.Map[K, V]): AsJavaDictionary[K, V] = new AsJavaDictionary(m) @@ -249,6 +260,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * @tparam K the type of the map keys * @tparam V the type of the map values * @param m the Scala `Map` to be converted + * @return an adapter exposing an `asJava` method that returns the corresponding Java `Map` */ implicit def mapAsJavaMapConverter[K, V](m : Map[K, V]): AsJava[ju.Map[K, V]] = new AsJava(mapAsJavaMap(m)) @@ -259,6 +271,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * @tparam K the type of the map keys * @tparam V the type of the map values * @param m the Scala `concurrent.Map` to be converted + * @return an adapter exposing an `asJava` method that returns the corresponding Java `ConcurrentMap` */ implicit def mapAsJavaConcurrentMapConverter[K, V](m: concurrent.Map[K, V]): AsJava[juc.ConcurrentMap[K, V]] = new AsJava(mapAsJavaConcurrentMap(m)) @@ -269,6 +282,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the iterator * @param i the Java `Iterator` to be converted + * @return an adapter exposing an `asScala` method that returns the corresponding Scala `Iterator` */ implicit def asScalaIteratorConverter[A](i : ju.Iterator[A]): AsScala[Iterator[A]] = new AsScala(asScalaIterator(i)) @@ -278,6 +292,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the enumeration * @param i the Java `Enumeration` to be converted + * @return an adapter exposing an `asScala` method that returns the corresponding Scala `Iterator` */ implicit def enumerationAsScalaIteratorConverter[A](i : ju.Enumeration[A]): AsScala[Iterator[A]] = new AsScala(enumerationAsScalaIterator(i)) @@ -287,6 +302,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the iterable * @param i the Java `Iterable` to be converted + * @return an adapter exposing an `asScala` method that returns the corresponding Scala `Iterable` */ implicit def iterableAsScalaIterableConverter[A](i : jl.Iterable[A]): AsScala[Iterable[A]] = new AsScala(iterableAsScalaIterable(i)) @@ -296,6 +312,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the collection * @param i the Java `Collection` to be converted + * @return an adapter exposing an `asScala` method that returns the corresponding Scala `Iterable` */ implicit def collectionAsScalaIterableConverter[A](i : ju.Collection[A]): AsScala[Iterable[A]] = new AsScala(collectionAsScalaIterable(i)) @@ -305,6 +322,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the list * @param l the Java `List` to be converted + * @return an adapter exposing an `asScala` method that returns the corresponding Scala mutable `Buffer` */ implicit def asScalaBufferConverter[A](l : ju.List[A]): AsScala[mutable.Buffer[A]] = new AsScala(asScalaBuffer(l)) @@ -314,6 +332,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * * @tparam A the element type of the set * @param s the Java `Set` to be converted + * @return an adapter exposing an `asScala` method that returns the corresponding Scala mutable `Set` */ implicit def asScalaSetConverter[A](s : ju.Set[A]): AsScala[mutable.Set[A]] = new AsScala(asScalaSet(s)) @@ -324,6 +343,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * @tparam K the type of the map keys * @tparam V the type of the map values * @param m the Java `Map` to be converted + * @return an adapter exposing an `asScala` method that returns the corresponding Scala mutable `Map` */ implicit def mapAsScalaMapConverter[K, V](m : ju.Map[K, V]): AsScala[mutable.Map[K, V]] = new AsScala(mapAsScalaMap(m)) @@ -334,6 +354,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * @tparam K the type of the map keys * @tparam V the type of the map values * @param m the Java `ConcurrentMap` to be converted + * @return an adapter exposing an `asScala` method that returns the corresponding Scala mutable `concurrent.Map` */ implicit def mapAsScalaConcurrentMapConverter[K, V](m: juc.ConcurrentMap[K, V]): AsScala[concurrent.Map[K, V]] = new AsScala(mapAsScalaConcurrentMap(m)) @@ -344,6 +365,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * @tparam K the type of the dictionary keys * @tparam V the type of the dictionary values * @param p the Java `Dictionary` to be converted + * @return an adapter exposing an `asScala` method that returns the corresponding Scala mutable `Map` */ implicit def dictionaryAsScalaMapConverter[K, V](p: ju.Dictionary[K, V]): AsScala[mutable.Map[K, V]] = new AsScala(dictionaryAsScalaMap(p)) @@ -352,6 +374,7 @@ object JavaConverters extends AsJavaConverters with AsScalaConverters { * @see [[propertiesAsScalaMap]] * * @param p the Java `Properties` to be converted + * @return an adapter exposing an `asScala` method that returns the corresponding Scala mutable `Map[String, String]` */ implicit def propertiesAsScalaMapConverter(p: ju.Properties): AsScala[mutable.Map[String, String]] = new AsScala(propertiesAsScalaMap(p)) diff --git a/library/src/scala/collection/Map.scala b/library/src/scala/collection/Map.scala index e79f994c5ed0..b2b6a1b93bb3 100644 --- a/library/src/scala/collection/Map.scala +++ b/library/src/scala/collection/Map.scala @@ -109,6 +109,8 @@ transparent trait MapOps[K, +V, +CC[_, _] <: IterableOps[?, AnyConstr, ?], +C] /** Returns a [[Stepper]] for the keys of this map. See method [[stepper]]. * * @tparam S the type of `Stepper` to use, determined by the implicit `StepperShape` + * @param shape the implicit `StepperShape` that selects the appropriate primitive or boxed `Stepper` for `K` + * @return a `Stepper` over the keys of this map, specialized for primitives when the resolved `StepperShape` corresponds to `Int`, `Long`, or `Double` */ def keyStepper[S <: Stepper[?]](implicit shape: StepperShape[K, S]): S = { import convert.impl._ @@ -124,6 +126,8 @@ transparent trait MapOps[K, +V, +CC[_, _] <: IterableOps[?, AnyConstr, ?], +C] /** Returns a [[Stepper]] for the values of this map. See method [[stepper]]. * * @tparam S the type of `Stepper` to use, determined by the implicit `StepperShape` + * @param shape the implicit `StepperShape` that selects the appropriate primitive or boxed `Stepper` for `V` + * @return a `Stepper` over the values of this map, specialized for primitives when the resolved `StepperShape` corresponds to `Int`, `Long`, or `Double` */ def valueStepper[S <: Stepper[?]](implicit shape: StepperShape[V, S]): S = { import convert.impl._ @@ -142,6 +146,7 @@ transparent trait MapOps[K, +V, +CC[_, _] <: IterableOps[?, AnyConstr, ?], +C] * @tparam K2 the key type of the returned map * @tparam V2 the value type of the returned map * @param it the iterable of key-value pairs to convert into a map + * @return a map of type `CC[K2, V2]` containing the key-value pairs from `it` */ @`inline` protected final def mapFromIterable[K2, V2](it: Iterable[(K2, V2)]^): CC[K2, V2]^{it} = mapFactory.from(it) @@ -457,6 +462,8 @@ object MapOps { * @tparam K the key type of the underlying map * @tparam V the value type of the underlying map * @tparam CC the type constructor of the underlying map + * @tparam C the concrete type of the underlying map (e.g. `HashMap[Int, String]`) + * @param mp the underlying map whose keys this set exposes; held by reference so the set reflects the map */ private[collection] class LazyKeySet[K, +V, +CC[_, _] <: IterableOps[?, AnyConstr, ?], +C](mp: MapOps[K, V, CC, C]) extends AbstractSet[K] with DefaultSerializable { def iterator: Iterator[K] = mp.keysIterator @@ -472,6 +479,8 @@ object MapOps { * @tparam K the key type of the underlying map * @tparam V the value type of the underlying map * @tparam CC the type constructor of the underlying map + * @tparam C the concrete type of the underlying map (e.g. `HashMap[Int, String]`) + * @param mp the underlying map whose keys are eagerly copied into this set at construction time */ private[collection] class StrictKeySet[K, +V, +CC[_, _] <: IterableOps[?, AnyConstr, ?], +C](@annotation.constructorOnly mp: MapOps[K, V, CC, C]^) extends AbstractSet[K] with DefaultSerializable { val allKeys = mp.keysIterator.to(mutable.LinkedHashSet) diff --git a/library/src/scala/collection/Seq.scala b/library/src/scala/collection/Seq.scala index 3d8faac0fe27..751fd2aeda3d 100644 --- a/library/src/scala/collection/Seq.scala +++ b/library/src/scala/collection/Seq.scala @@ -86,6 +86,7 @@ transparent trait SeqOps[+A, +CC[_], +C] extends Any * not be assumed to be efficient unless you have an `IndexedSeq`. * * @param i the index of the element to retrieve, zero-based + * @return the element at index `i` */ @throws[IndexOutOfBoundsException] def apply(i: Int): A diff --git a/library/src/scala/collection/Set.scala b/library/src/scala/collection/Set.scala index e7b497db01fa..111b98de1a47 100644 --- a/library/src/scala/collection/Set.scala +++ b/library/src/scala/collection/Set.scala @@ -87,6 +87,7 @@ trait Set[A] * * @tparam A the element type of the set * @tparam CC the type constructor for the set's collection type + * @tparam C the self type of this set, used as the return type for transformation operations that preserve the collection's specific type */ transparent trait SetOps[A, +CC[_], +C <: SetOps[A, CC, C]] extends IterableOps[A, CC, C] diff --git a/library/src/scala/collection/SortedMap.scala b/library/src/scala/collection/SortedMap.scala index 50c8ba613c86..aacd347ddb07 100644 --- a/library/src/scala/collection/SortedMap.scala +++ b/library/src/scala/collection/SortedMap.scala @@ -75,6 +75,8 @@ transparent trait SortedMapOps[K, +V, +CC[X, Y] <: Map[X, Y] & SortedMapOps[X, Y * @tparam K2 the type of the keys in the resulting sorted map * @tparam V2 the type of the values in the resulting sorted map * @param it the iterable of key-value pairs to convert into a sorted map + * @param ordering the ordering used to sort the keys of the resulting sorted map + * @return a new sorted map containing the key-value pairs from `it`, ordered by `ordering` */ @`inline` protected final def sortedMapFromIterable[K2, V2](it: Iterable[(K2, V2)]^)(implicit ordering: Ordering[K2]): CC[K2, V2] = sortedMapFactory.from(it) @@ -205,6 +207,7 @@ transparent trait SortedMapOps[K, +V, +CC[X, Y] <: Map[X, Y] & SortedMapOps[X, Y * @tparam K2 the type of the keys in the returned sorted map * @tparam V2 the type of the values in the returned sorted map * @param pf the partial function which filters and maps the $coll. + * @param ordering the ordering to use for the keys of the returned sorted map * @return a new $coll resulting from applying the given partial function * `pf` to each element on which it is defined and collecting the results. * The order of the elements is preserved. diff --git a/library/src/scala/collection/SortedOps.scala b/library/src/scala/collection/SortedOps.scala index 7a39b0c2c28d..91f63c4eb17d 100644 --- a/library/src/scala/collection/SortedOps.scala +++ b/library/src/scala/collection/SortedOps.scala @@ -55,6 +55,7 @@ transparent trait SortedOps[A, +C] { * * @param from The lower-bound (inclusive) of the ranged projection. * @param until The upper-bound (exclusive) of the ranged projection. + * @return a ranged projection of this collection containing only elements greater than or equal to `from` and less than `until` */ def range(from: A, until: A): C = rangeImpl(Some(from), Some(until)) @@ -68,6 +69,7 @@ transparent trait SortedOps[A, +C] { /** Creates a ranged projection of this collection with no upper-bound. * * @param from The lower-bound (inclusive) of the ranged projection. + * @return a ranged projection of this collection containing only elements greater than or equal to `from` */ def rangeFrom(from: A): C = rangeImpl(Some(from), None) @@ -81,6 +83,7 @@ transparent trait SortedOps[A, +C] { /** Creates a ranged projection of this collection with no lower-bound. * * @param until The upper-bound (exclusive) of the ranged projection. + * @return a ranged projection of this collection containing only elements less than `until` */ def rangeUntil(until: A): C = rangeImpl(None, Some(until)) @@ -91,7 +94,9 @@ transparent trait SortedOps[A, +C] { final def to(to: A): C = rangeTo(to) /** Creates a range projection of this collection with no lower-bound. + * * @param to The upper-bound (inclusive) of the ranged projection. + * @return a ranged projection of this collection containing only elements less than or equal to `to` */ def rangeTo(to: A): C } diff --git a/library/src/scala/collection/SortedSet.scala b/library/src/scala/collection/SortedSet.scala index 17a43942bb45..279fe1e09679 100644 --- a/library/src/scala/collection/SortedSet.scala +++ b/library/src/scala/collection/SortedSet.scala @@ -74,6 +74,7 @@ transparent trait SortedSetOps[A, +CC[X] <: SortedSet[X], +C <: SortedSetOps[A, * be more efficient than x.from(y).iterator * * @param start The lower-bound (inclusive) of the iterator + * @return an iterator over all elements greater than or equal to `start`, in this collection's ordering */ def iteratorFrom(start: A): Iterator[A] @@ -122,6 +123,7 @@ transparent trait SortedSetOps[A, +CC[X] <: SortedSet[X], +C <: SortedSetOps[A, * * @tparam B the element type of the returned collection. * @param f the function to apply to each element. + * @param ev the `Ordering` for the new element type `B`, required to build the resulting sorted collection * @return a new $coll resulting from applying the given function * `f` to each element of this $coll and collecting the results. */ @@ -133,6 +135,7 @@ transparent trait SortedSetOps[A, +CC[X] <: SortedSet[X], +C <: SortedSetOps[A, * * @tparam B the element type of the returned collection. * @param f the function to apply to each element. + * @param ev the `Ordering` for the new element type `B`, required to build the resulting sorted collection * @return a new $coll resulting from applying the given collection-valued function * `f` to each element of this $coll and concatenating the results. */ @@ -145,6 +148,7 @@ transparent trait SortedSetOps[A, +CC[X] <: SortedSet[X], +C <: SortedSetOps[A, * * @tparam B the type of the second half of the returned pairs * @param that The iterable providing the second half of each result pair + * @param ev the `Ordering` for the resulting pair type `(A, B)`, required to build the resulting sorted collection * @return a new $coll containing pairs consisting of corresponding elements of this $coll and `that`. * The length of the returned collection is the minimum of the lengths of this $coll and `that`. */ @@ -159,6 +163,7 @@ transparent trait SortedSetOps[A, +CC[X] <: SortedSet[X], +C <: SortedSetOps[A, * * @tparam B the element type of the returned collection. * @param pf the partial function which filters and maps the $coll. + * @param ev the `Ordering` for the new element type `B`, required to build the resulting sorted collection * @return a new $coll resulting from applying the given partial function * `pf` to each element on which it is defined and collecting the results. * The order of the elements is preserved. @@ -177,6 +182,7 @@ object SortedSetOps { * * @tparam A the element type of the sorted collection * @tparam IterableCC the type constructor for the unsorted collection type + * @tparam CC the type constructor for the sorted collection type, which must be a subtype of `SortedSet` */ class WithFilter[+A, +IterableCC[_], +CC[X] <: SortedSet[X]]( self: SortedSetOps[A, CC, ?] & IterableOps[A, IterableCC, ?], diff --git a/library/src/scala/collection/StepperShape.scala b/library/src/scala/collection/StepperShape.scala index 51d6a1b6b56a..73aac3c06468 100644 --- a/library/src/scala/collection/StepperShape.scala +++ b/library/src/scala/collection/StepperShape.scala @@ -33,6 +33,7 @@ sealed trait StepperShape[-T, S <: Stepper[?]] { self => * This is an identity operation for reference shapes. * * @param st the boxed `AnyStepper` to convert into a possibly specialized stepper + * @return a sequential `Stepper` of shape `S` that unboxes elements from `st`, or `st` itself for reference shapes */ def seqUnbox(st: AnyStepper[T]^): S^{st} @@ -40,6 +41,7 @@ sealed trait StepperShape[-T, S <: Stepper[?]] { self => * This is an identity operation for reference shapes. * * @param st the boxed `AnyStepper` with `EfficientSplit` capability to convert into a possibly specialized stepper + * @return a parallel `Stepper` of shape `S` with `EfficientSplit` that unboxes elements from `st`, or `st` itself for reference shapes */ def parUnbox(st: (AnyStepper[T] & EfficientSplit)^): (S & EfficientSplit)^{st} } diff --git a/library/src/scala/collection/StrictOptimizedIterableOps.scala b/library/src/scala/collection/StrictOptimizedIterableOps.scala index a0d03d6d38de..8194e20480ba 100644 --- a/library/src/scala/collection/StrictOptimizedIterableOps.scala +++ b/library/src/scala/collection/StrictOptimizedIterableOps.scala @@ -256,6 +256,7 @@ transparent trait StrictOptimizedIterableOps[+A, +CC[_], +C] * $willForceEvaluation * * @param n the number of elements to take from the end of this collection + * @return a new collection containing the last `n` elements of this collection, or all elements if `n` is greater than the size, or an empty collection if `n` is non-positive */ override def takeRight(n: Int): C = { val b = newSpecificBuilder @@ -275,6 +276,7 @@ transparent trait StrictOptimizedIterableOps[+A, +CC[_], +C] * $willForceEvaluation * * @param n the number of elements to drop from the end of this collection + * @return a new collection containing all elements of this collection except the last `n`, or an empty collection if `n` is greater than or equal to the size, or all elements if `n` is non-positive */ override def dropRight(n: Int): C = { val b = newSpecificBuilder diff --git a/library/src/scala/collection/StrictOptimizedSeqOps.scala b/library/src/scala/collection/StrictOptimizedSeqOps.scala index d649e394efbf..af9113d0f16c 100644 --- a/library/src/scala/collection/StrictOptimizedSeqOps.scala +++ b/library/src/scala/collection/StrictOptimizedSeqOps.scala @@ -20,6 +20,7 @@ import language.experimental.captureChecking * * @tparam A the element type of the sequence * @tparam CC the type constructor of the collection + * @tparam C the type of the sequence itself */ transparent trait StrictOptimizedSeqOps [+A, +CC[_] <: caps.Pure, +C] extends Any with SeqOps[A, CC, C] with StrictOptimizedIterableOps[A, CC, C] with caps.Pure { diff --git a/library/src/scala/collection/StringOps.scala b/library/src/scala/collection/StringOps.scala index 3dc5dca1dbb1..e9764e565839 100644 --- a/library/src/scala/collection/StringOps.scala +++ b/library/src/scala/collection/StringOps.scala @@ -167,6 +167,7 @@ object StringOps { /** Creates a new non-strict filter which combines this filter with the given predicate. * * @param q the additional predicate to apply to each char + * @return a new `WithFilter` whose predicate is the conjunction of this filter's predicate and `q` */ def withFilter(q: Char => Boolean): WithFilter^{this, q} = new WithFilter(a => p(a) && q(a), s) } @@ -204,6 +205,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** Gets the char at the specified index. * * @param i the zero-based index of the char to retrieve + * @return the char at position `i` in this string */ @inline def apply(i: Int): Char = s.charAt(i) @@ -432,6 +434,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * * @tparam B the element type of the returned collection, a supertype of `Char` * @param elem the element to prepend + * @return a new collection consisting of `elem` followed by all chars of this string */ def prepended[B >: Char](elem: B): immutable.IndexedSeq[B] = { val b = immutable.IndexedSeq.newBuilder[B] @@ -447,6 +450,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** A copy of the string with an char prepended. * * @param c the char to prepend + * @return a new string consisting of `c` followed by all chars of this string */ def prepended(c: Char): String = new JStringBuilder(s.length + 1).append(c).append(s).toString @@ -458,6 +462,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * * @tparam B the element type of the returned collection, a supertype of `Char` * @param prefix the collection to prepend + * @return a new collection consisting of all elements of `prefix` followed by all chars of this string */ def prependedAll[B >: Char](prefix: IterableOnce[B]^): immutable.IndexedSeq[B] = { val b = immutable.IndexedSeq.newBuilder[B] @@ -474,6 +479,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** A copy of the string with another string prepended. * * @param prefix the string to prepend + * @return a new string consisting of `prefix` followed by this string */ def prependedAll(prefix: String): String = prefix + s @@ -484,6 +490,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * * @tparam B the element type of the returned collection, a supertype of `Char` * @param elem the element to append + * @return a new collection consisting of all chars of this string followed by `elem` */ def appended[B >: Char](elem: B): immutable.IndexedSeq[B] = { val b = immutable.IndexedSeq.newBuilder[B] @@ -499,6 +506,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** A copy of the string with an element appended. * * @param c the char to append + * @return a new string consisting of all chars of this string followed by `c` */ def appended(c: Char): String = new JStringBuilder(s.length + 1).append(s).append(c).toString @@ -510,6 +518,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * * @tparam B the element type of the returned collection, a supertype of `Char` * @param suffix the collection to append + * @return a new collection consisting of all chars of this string followed by all elements of `suffix` */ @inline def appendedAll[B >: Char](suffix: IterableOnce[B]^): immutable.IndexedSeq[B] = concat(suffix) @@ -521,6 +530,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** A copy of the string with another string appended. * * @param suffix the string to append + * @return a new string consisting of this string followed by `suffix` */ @inline def appendedAll(suffix: String): String = s + suffix @@ -651,6 +661,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** Appends this string to a string builder. * * @param b the string builder to append to + * @return the string builder `b` with this string appended */ @inline final def addString(b: StringBuilder): b.type = b.append(s) @@ -658,6 +669,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * * @param b the string builder to append to * @param sep the separator string inserted between chars + * @return the string builder `b` with this string's chars appended, separated by `sep` */ @inline final def addString(b: StringBuilder, sep: String): b.type = addString(b, "", sep, "") @@ -668,6 +680,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * @param start the string to prepend before all chars * @param sep the separator string inserted between chars * @param end the string to append after all chars + * @return the string builder `b` with `start` prepended, this string's chars separated by `sep`, and `end` appended */ final def addString(b: StringBuilder, start: String, sep: String, end: String): b.type = { val jsb = b.underlying @@ -796,6 +809,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * start with `prefix`, it is returned unchanged. * * @param prefix the prefix to strip from this string + * @return this string with the leading `prefix` removed, or this string unchanged if it does not start with `prefix` */ def stripPrefix(prefix: String): String = if (s.startsWith(prefix)) s.substring(prefix.length) @@ -805,6 +819,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * end with `suffix`, it is returned unchanged. * * @param suffix the suffix to strip from this string + * @return this string with the trailing `suffix` removed, or this string unchanged if it does not end with `suffix` */ def stripSuffix(suffix: String): String = if (s.endsWith(suffix)) s.substring(0, s.length - suffix.length) @@ -931,19 +946,22 @@ final class StringOps(private val s: String) extends AnyVal { self => def r(groupNames: String*): Regex = new Regex(s, groupNames*) /** + * @return `true` if the string equals "true" (case-insensitive), `false` if the string equals "false" (case-insensitive) * @throws java.lang.IllegalArgumentException If the string does not contain a parsable `Boolean`. */ def toBoolean: Boolean = toBooleanImpl(s) /** Tries to parse as a `Boolean`. - * @return `Some(true)` if the string is "true" case insensitive, - * `Some(false)` if the string is "false" case insensitive, + * @return `Some(true)` if the string equals "true" (case-insensitive), + * `Some(false)` if the string equals "false" (case-insensitive), * and `None` if the string is anything else * @throws java.lang.NullPointerException if the string is `null` */ def toBooleanOption: Option[Boolean] = StringParsers.parseBool(s) /** Parses as a `Byte` (string must contain only decimal digits and optional leading `-` or `+`). + * + * @return the `Byte` value parsed from this string * @throws java.lang.NumberFormatException If the string does not contain a parsable `Byte`. */ def toByte: Byte = java.lang.Byte.parseByte(s) @@ -955,6 +973,8 @@ final class StringOps(private val s: String) extends AnyVal { self => def toByteOption: Option[Byte] = StringParsers.parseByte(s) /** Parses as a `Short` (string must contain only decimal digits and optional leading `-` or `+`). + * + * @return the `Short` value parsed from this string * @throws java.lang.NumberFormatException If the string does not contain a parsable `Short`. */ def toShort: Short = java.lang.Short.parseShort(s) @@ -966,6 +986,8 @@ final class StringOps(private val s: String) extends AnyVal { self => def toShortOption: Option[Short] = StringParsers.parseShort(s) /** Parses as an `Int` (string must contain only decimal digits and optional leading `-` or `+`). + * + * @return the `Int` value parsed from this string * @throws java.lang.NumberFormatException If the string does not contain a parsable `Int`. */ def toInt: Int = java.lang.Integer.parseInt(s) @@ -977,6 +999,8 @@ final class StringOps(private val s: String) extends AnyVal { self => def toIntOption: Option[Int] = StringParsers.parseInt(s) /** Parses as a `Long` (string must contain only decimal digits and optional leading `-` or `+`). + * + * @return the `Long` value parsed from this string * @throws java.lang.NumberFormatException If the string does not contain a parsable `Long`. */ def toLong: Long = java.lang.Long.parseLong(s) @@ -988,6 +1012,8 @@ final class StringOps(private val s: String) extends AnyVal { self => def toLongOption: Option[Long] = StringParsers.parseLong(s) /** Parses as a `Float` (surrounding whitespace is removed with a `trim`). + * + * @return the `Float` value parsed from this string * @throws java.lang.NumberFormatException If the string does not contain a parsable `Float`. * @throws java.lang.NullPointerException If the string is null. */ @@ -1000,6 +1026,8 @@ final class StringOps(private val s: String) extends AnyVal { self => def toFloatOption: Option[Float] = StringParsers.parseFloat(s) /** Parses as a `Double` (surrounding whitespace is removed with a `trim`). + * + * @return the `Double` value parsed from this string * @throws java.lang.NumberFormatException If the string does not contain a parsable `Double`. * @throws java.lang.NullPointerException If the string is null. */ @@ -1085,6 +1113,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** Counts the number of chars in this string which satisfy a predicate. * * @param p the predicate used to test chars + * @return the number of chars in this string that satisfy the predicate `p` */ def count(p: (Char) => Boolean): Int = { var i, res = 0 @@ -1268,12 +1297,16 @@ final class StringOps(private val s: String) extends AnyVal { self => def withFilter(p: Char => Boolean): StringOps.WithFilter^{p} = new StringOps.WithFilter(p, s) /** The rest of the string without its first char. + * + * @return a string containing all chars of this string except the first * @throws UnsupportedOperationException if the string is empty. * @note $unicodeunaware */ def tail: String = if(s.isEmpty) throw new UnsupportedOperationException("tail of empty String") else slice(1, s.length) /** The initial part of the string without its last char. + * + * @return a string containing all chars of this string except the last * @throws UnsupportedOperationException if the string is empty. * @note $unicodeunaware */ @@ -1283,6 +1316,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * @note $unicodeunaware * * @param n the number of chars to take from the beginning of this string + * @return a string containing the first `n` chars of this string, the entire string if `n` exceeds its length, or the empty string if `n <= 0` */ def take(n: Int): String = slice(0, min(n, s.length)) @@ -1290,6 +1324,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * @note $unicodeunaware * * @param n the number of chars to drop from the beginning of this string + * @return a string containing the chars of this string after the first `n`, the empty string if `n` exceeds its length, or the entire string if `n <= 0` */ def drop(n: Int): String = slice(min(n, s.length), s.length) @@ -1297,6 +1332,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * @note $unicodeunaware * * @param n the number of chars to take from the end of this string + * @return a string containing the last `n` chars of this string, the entire string if `n` exceeds its length, or the empty string if `n <= 0` */ def takeRight(n: Int): String = drop(s.length - max(n, 0)) @@ -1304,6 +1340,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * @note $unicodeunaware * * @param n the number of chars to drop from the end of this string + * @return a string containing the chars of this string except the last `n`, the empty string if `n` exceeds its length, or the entire string if `n <= 0` */ def dropRight(n: Int): String = take(s.length - max(n, 0)) @@ -1332,6 +1369,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** Selects all chars of this string which satisfy a predicate. * * @param pred the predicate used to test chars + * @return a new string consisting of all chars of this string that satisfy `pred` */ def filter(pred: Char => Boolean): String = { val len = s.length @@ -1348,6 +1386,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** Selects all chars of this string which do not satisfy a predicate. * * @param pred the predicate used to test chars + * @return a new string consisting of all chars of this string that do not satisfy `pred` */ @inline def filterNot(pred: Char => Boolean): String = filter(c => !pred(c)) @@ -1357,6 +1396,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * or the end of the array is reached * * @param xs the array to fill. + * @return the number of chars copied into `xs` */ @inline def copyToArray(xs: Array[Char]): Int = copyToArray(xs, 0, Int.MaxValue) @@ -1368,6 +1408,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * * @param xs the array to fill. * @param start the starting index. + * @return the number of chars copied into `xs` */ @inline def copyToArray(xs: Array[Char], start: Int): Int = copyToArray(xs, start, Int.MaxValue) @@ -1380,6 +1421,7 @@ final class StringOps(private val s: String) extends AnyVal { self => * @param xs the array to fill. * @param start the starting index. * @param len the maximal number of elements to copy. + * @return the number of chars copied into `xs` */ def copyToArray(xs: Array[Char], start: Int, len: Int): Int = { val copied = IterableOnce.elemsToCopyToArray(s.length, xs.length, start, len) @@ -1426,6 +1468,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** Tests whether a predicate holds for at least one char of this string. * * @param p the predicate used to test chars + * @return `true` if at least one char of this string satisfies `p`, `false` otherwise */ def exists(p: Char => Boolean): Boolean = indexWhere(p) != -1 @@ -1454,6 +1497,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** Takes longest prefix of chars that satisfy a predicate. * * @param p the predicate used to test chars + * @return the longest prefix of this string whose chars all satisfy the predicate `p` */ def takeWhile(p: Char => Boolean): String = indexWhere(c => !p(c)) match { case -1 => s @@ -1498,6 +1542,7 @@ final class StringOps(private val s: String) extends AnyVal { self => /** A pair of, first, all chars that satisfy predicate `p` and, second, all chars that do not. * * @param p the predicate used to partition chars + * @return a pair of strings: the first containing all chars that satisfy `p`, and the second containing all chars that do not */ def partition(p: Char => Boolean): (String, String) = { val res1, res2 = new JStringBuilder diff --git a/library/src/scala/collection/convert/StreamExtensions.scala b/library/src/scala/collection/convert/StreamExtensions.scala index cd8ee14e1600..62ea7da6811e 100644 --- a/library/src/scala/collection/convert/StreamExtensions.scala +++ b/library/src/scala/collection/convert/StreamExtensions.scala @@ -38,7 +38,11 @@ trait StreamExtensions { * collection contains primitive values, a corresponding specialized Stream is returned (e.g., * [[java.util.stream.IntStream `IntStream`]]). * - * @tparam S the type of Java Stream to create, determined by the element type `A` + * @tparam S the type of Java Stream to create, determined by the element type `A` via the implicit `StreamShape` + * @tparam St the type of `Stepper` used to traverse the collection's elements + * @param s implicit evidence connecting element type `A` to the appropriate Java Stream and Stepper types + * @param st implicit evidence selecting the appropriate `Stepper` shape for element type `A` + * @return a sequential Java Stream of type `S` containing the elements of this collection */ def asJavaSeqStream[S <: BaseStream[?, ?], St <: Stepper[?]](implicit s: StreamShape[A, S, St], st: StepperShape[A, St]): S = s.fromStepper(cc.stepper, par = false) @@ -55,6 +59,7 @@ trait StreamExtensions { * [[java.util.stream.IntStream `IntStream`]]). * * @tparam S the type of Java Stream to create, determined by the element type `A` + * @tparam St the type of `Stepper` used to traverse the collection's elements, required to support efficient splitting */ def asJavaParStream[S <: BaseStream[?, ?], St <: Stepper[?]](implicit s: StreamShape[A, S, St], @@ -72,6 +77,10 @@ trait StreamExtensions { * [[java.util.stream.IntStream `IntStream`]]). * * @tparam S the type of Java Stream to create, determined by the key type `K` + * @tparam St the type of `Stepper` used to traverse the map's keys + * @param s implicit evidence connecting key type `K` to the appropriate Java Stream and Stepper types + * @param st implicit evidence selecting the appropriate `Stepper` shape for key type `K` + * @return a sequential Java Stream of type `S` containing the keys of this map */ def asJavaSeqKeyStream[S <: BaseStream[?, ?], St <: Stepper[?]](implicit s: StreamShape[K, S, St], st: StepperShape[K, St]): S = s.fromStepper(cc.keyStepper, par = false) @@ -81,6 +90,10 @@ trait StreamExtensions { * [[java.util.stream.IntStream `IntStream`]]). * * @tparam S the type of Java Stream to create, determined by the value type `V` + * @tparam St the type of `Stepper` used to traverse the map's values + * @param s implicit evidence connecting value type `V` to the appropriate Java Stream and Stepper types + * @param st implicit evidence selecting the appropriate `Stepper` shape for value type `V` + * @return a sequential Java Stream of type `S` containing the values of this map */ def asJavaSeqValueStream[S <: BaseStream[?, ?], St <: Stepper[?]](implicit s: StreamShape[V, S, St], st: StepperShape[V, St]): S = s.fromStepper(cc.valueStepper, par = false) @@ -90,6 +103,10 @@ trait StreamExtensions { * this map. * * @tparam S the type of Java Stream to create, determined by the pair type `(K, V)` + * @tparam St the type of `Stepper` used to traverse the map's key-value pairs + * @param s implicit evidence connecting pair type `(K, V)` to the appropriate Java Stream and Stepper types + * @param st implicit evidence selecting the appropriate `Stepper` shape for pair type `(K, V)` + * @return a sequential Java Stream of type `S` containing the `(key, value)` pairs of this map */ def asJavaSeqStream[S <: BaseStream[?, ?], St <: Stepper[?]](implicit s: StreamShape[(K, V), S, St], st: StepperShape[(K, V), St]): S = s.fromStepper(cc.stepper, par = false) @@ -106,6 +123,7 @@ trait StreamExtensions { * [[java.util.stream.IntStream `IntStream`]]). * * @tparam S the type of Java Stream to create, determined by the key type `K` + * @tparam St the type of `Stepper` used to traverse the map's keys, required to support efficient splitting */ def asJavaParKeyStream[S <: BaseStream[?, ?], St <: Stepper[?]](implicit s: StreamShape[K, S, St], @@ -119,6 +137,7 @@ trait StreamExtensions { * [[java.util.stream.IntStream `IntStream`]]). * * @tparam S the type of Java Stream to create, determined by the value type `V` + * @tparam St the type of `Stepper` used to traverse the map's values, required to support efficient splitting */ def asJavaParValueStream[S <: BaseStream[?, ?], St <: Stepper[?]](implicit s: StreamShape[V, S, St], @@ -132,6 +151,7 @@ trait StreamExtensions { * this map. * * @tparam S the type of Java Stream to create, determined by the pair type `(K, V)` + * @tparam St the type of `Stepper` used to traverse the map's key-value pairs, required to support efficient splitting */ def asJavaParStream[S <: BaseStream[?, ?], St <: Stepper[?]](implicit s: StreamShape[(K, V), S, St], @@ -149,6 +169,10 @@ trait StreamExtensions { * [[java.util.stream.IntStream `IntStream`]]). * * @tparam S the type of Java Stream to create, determined by the element type `A` + * @tparam St the type of `Stepper` used to traverse the elements + * @param s implicit evidence connecting element type `A` to the appropriate Java Stream and Stepper types + * @param st implicit evidence selecting the appropriate `Stepper` shape for element type `A`; also used to unbox an `AnyStepper` to a specialized stepper when needed + * @return a sequential Java Stream of type `S` containing the elements yielded by this stepper */ def asJavaSeqStream[S <: BaseStream[?, ?], St <: Stepper[?]](implicit s: StreamShape[A, S, St], st: StepperShape[A, St]): S = { val sStepper = stepper match { @@ -165,6 +189,10 @@ trait StreamExtensions { * [[java.util.stream.IntStream `IntStream`]]). * * @tparam S the type of Java Stream to create, determined by the element type `A` + * @tparam St the type of `Stepper` used to traverse the elements + * @param s implicit evidence connecting element type `A` to the appropriate Java Stream and Stepper types + * @param st implicit evidence selecting the appropriate `Stepper` shape for element type `A`; also used to unbox an `AnyStepper with EfficientSplit` to a specialized stepper when needed + * @return a parallel Java Stream of type `S` containing the elements yielded by this stepper */ def asJavaParStream[S <: BaseStream[?, ?], St <: Stepper[?]](implicit s: StreamShape[A, S, St], st: StepperShape[A, St]): S = { val sStepper = (stepper: @unchecked) match { @@ -302,6 +330,7 @@ trait StreamExtensions { * * @tparam S the resulting primitive stream type (e.g., `IntStream`, `LongStream`, `DoubleStream`) * @param unboxer implicit conversion from boxed `Stream[A]` to primitive stream `S` + * @return a primitive Java Stream of type `S` containing the unboxed elements of this stream */ def asJavaPrimitiveStream[S](implicit unboxer: StreamUnboxer[A, S]): S = unboxer(stream) } diff --git a/library/src/scala/collection/convert/impl/BinaryTreeStepper.scala b/library/src/scala/collection/convert/impl/BinaryTreeStepper.scala index 5f9bfdff2935..edde68d61d96 100644 --- a/library/src/scala/collection/convert/impl/BinaryTreeStepper.scala +++ b/library/src/scala/collection/convert/impl/BinaryTreeStepper.scala @@ -61,6 +61,7 @@ extends EfficientSplit { * may have things to its right. * * @param from the tree node from which to begin unrolling leftward + * @return the leftmost node reached, which has no left child and is not placed on the stack */ @tailrec protected final def unroll(from: T): T = { val l = left(from) @@ -80,6 +81,7 @@ extends EfficientSplit { * on the stack. * * @param node the tree node to detach, whose left subtree has already been visited + * @return the detached `node`, ready to be consumed by the stepper */ protected final def detach(node: T): node.type = { val r = right(node) diff --git a/library/src/scala/collection/convert/impl/ChampStepper.scala b/library/src/scala/collection/convert/impl/ChampStepper.scala index ec7a6c7dd306..2e39a36fe445 100644 --- a/library/src/scala/collection/convert/impl/ChampStepper.scala +++ b/library/src/scala/collection/convert/impl/ChampStepper.scala @@ -24,6 +24,9 @@ import scala.collection.immutable.Node * * @tparam A the element type produced by this stepper * @tparam T the CHAMP trie node type, with recursive bound `T <: Node[T]` + * @tparam Sub the public stepper supertype returned by `trySplit` + * @tparam Semi the concrete self-type produced by `semiclone`, a subtype of `Sub` + * @param maxSize the maximum number of remaining elements this stepper will produce */ private[collection] abstract class ChampStepperBase[ A, T <: Node[T], Sub, Semi <: Sub & ChampStepperBase[A, T, ?, ?] diff --git a/library/src/scala/collection/convert/impl/IteratorStepper.scala b/library/src/scala/collection/convert/impl/IteratorStepper.scala index 39211d25fab9..21b7a5667e63 100644 --- a/library/src/scala/collection/convert/impl/IteratorStepper.scala +++ b/library/src/scala/collection/convert/impl/IteratorStepper.scala @@ -124,6 +124,7 @@ private[collection] class LongIteratorStepper(_underlying: Iterator[Long] | Null * @tparam A the element type of the iterator being stepped through * @tparam SP the specific `Stepper` subtype, bounded by `Stepper[A]`, used for proxied delegation and split results * @tparam Semi the concrete stepper subtype returned by `semiclone()`, must extend `SP` + * @param underlying the source `Iterator` to step through, or `null` for steppers created via `semiclone()` during a split, which delegate to `proxied` instead */ private[convert] abstract class IteratorStepperBase[A, SP <: Stepper[A], Semi <: SP](final protected val underlying: Iterator[A] | Null) { final protected var nextChunkSize = 16 diff --git a/library/src/scala/collection/convert/impl/StringStepper.scala b/library/src/scala/collection/convert/impl/StringStepper.scala index 32406c704e6e..59255f7a53fb 100644 --- a/library/src/scala/collection/convert/impl/StringStepper.scala +++ b/library/src/scala/collection/convert/impl/StringStepper.scala @@ -23,6 +23,8 @@ import scala.collection.{IntStepper, Stepper} /** Implements `Stepper` on a `String` where you step through chars packed into `Int`. * * @param underlying the `String` to step through + * @param _i0 the starting char index (inclusive) into the string + * @param _iN the ending char index (exclusive) into the string */ private[collection] final class CharStringStepper(underlying: String, _i0: Int, _iN: Int) extends IndexedStepperBase[IntStepper, CharStringStepper](_i0, _iN) diff --git a/library/src/scala/collection/generic/CommonErrors.scala b/library/src/scala/collection/generic/CommonErrors.scala index 83a347963135..f7f0d97a2ad6 100644 --- a/library/src/scala/collection/generic/CommonErrors.scala +++ b/library/src/scala/collection/generic/CommonErrors.scala @@ -22,6 +22,7 @@ private[collection] object CommonErrors { * * @param index the index that was out of bounds * @param max the upper bound of the valid index range + * @return a new `IndexOutOfBoundsException` whose message reports `index` along with the valid range from `0` to `max` */ @noinline def indexOutOfBounds(index: Int, max: Int): IndexOutOfBoundsException = @@ -30,6 +31,7 @@ private[collection] object CommonErrors { /** IndexOutOfBounds exception with an unknown max index. * * @param index the index that was out of bounds + * @return a new `IndexOutOfBoundsException` with a message reporting `index` and an unknown upper bound */ @noinline def indexOutOfBounds(index: Int): IndexOutOfBoundsException = diff --git a/library/src/scala/collection/generic/IsIterable.scala b/library/src/scala/collection/generic/IsIterable.scala index 95ed542cb447..00177a5b21a4 100644 --- a/library/src/scala/collection/generic/IsIterable.scala +++ b/library/src/scala/collection/generic/IsIterable.scala @@ -113,6 +113,7 @@ transparent trait IsIterable[Repr] extends IsIterableOnce[Repr] { /** A conversion from the type `Repr` to `IterableOps[A, Iterable, C]`. * * @param coll the collection or value to convert to `IterableOps[A, Iterable, C]` + * @return an `IterableOps[A, Iterable, C]` instance that exposes the iterable operations of `coll` */ def apply(coll: Repr): IterableOps[A, Iterable, C] diff --git a/library/src/scala/collection/generic/IsIterableOnce.scala b/library/src/scala/collection/generic/IsIterableOnce.scala index 695bdfbd7e3f..7d2226adc0f9 100644 --- a/library/src/scala/collection/generic/IsIterableOnce.scala +++ b/library/src/scala/collection/generic/IsIterableOnce.scala @@ -56,6 +56,7 @@ transparent trait IsIterableOnce[Repr] { /** A conversion from the representation type `Repr` to an `IterableOnce[A]`. * * @param coll the representation type instance to view as an `IterableOnce[A]` + * @return an `IterableOnce[A]` view of `coll` */ def apply(coll: Repr): IterableOnce[A] diff --git a/library/src/scala/collection/package.scala b/library/src/scala/collection/package.scala index 1095b0a6ae28..ae1206a483ed 100644 --- a/library/src/scala/collection/package.scala +++ b/library/src/scala/collection/package.scala @@ -67,6 +67,8 @@ package object collection { * * @tparam A the element type of the sequence * @tparam CC the type constructor of the sequence (e.g., `List`, `Vector`) + * @tparam C the concrete sequence type, providing `SeqOps[A, CC, C]` for `head`/`tail` operations + * @param t the sequence to deconstruct into its head and tail * @return `Some((head, tail))` if the sequence is non-empty, `None` otherwise */ def unapply[A, CC[_] <: Seq[?], C <: SeqOps[A, CC, C]](t: (C & SeqOps[A, CC, C])^): Option[(A, C^{t})] = @@ -80,6 +82,8 @@ package object collection { * * @tparam A the element type of the sequence * @tparam CC the type constructor of the sequence (e.g., `List`, `Vector`) + * @tparam C the concrete sequence type, providing `SeqOps[A, CC, C]` for `init`/`last` operations + * @param t the sequence to deconstruct into its init and last element * @return `Some((init, last))` if the sequence is non-empty, `None` otherwise */ def unapply[A, CC[_] <: Seq[?], C <: SeqOps[A, CC, C]](t: (C & SeqOps[A, CC, C])^): Option[(C^{t}, A)] =