diff --git a/library/src/scala/concurrent/BlockContext.scala b/library/src/scala/concurrent/BlockContext.scala index 4bd97a58f466..1ba884408ee7 100644 --- a/library/src/scala/concurrent/BlockContext.scala +++ b/library/src/scala/concurrent/BlockContext.scala @@ -92,6 +92,7 @@ object BlockContext { * @tparam T the result type of `body` * @param blockContext the `BlockContext` to install for the duration of `body` * @param body the code to execute with the given `blockContext` installed + * @return the result of executing `body` */ final def withBlockContext[T](blockContext: BlockContext)(body: => T): T = { val old = contextLocal.get // can be null diff --git a/library/src/scala/concurrent/Future.scala b/library/src/scala/concurrent/Future.scala index b80f3e492649..10e991f3be31 100644 --- a/library/src/scala/concurrent/Future.scala +++ b/library/src/scala/concurrent/Future.scala @@ -284,6 +284,7 @@ trait Future[+T] extends Awaitable[T] { * * @tparam S the type of the returned `Future` * @param ev evidence that `T` is itself a `Future[S]` + * @return a `Future` with the result of the inner `Future` * @group Transformations */ def flatten[S](implicit ev: T <:< Future[S]): Future[S] = flatMap(ev)(using parasitic) @@ -325,6 +326,7 @@ trait Future[+T] extends Awaitable[T] { * * @param p the predicate to apply to the successful result of this `Future` * @param executor the `ExecutionContext` on which the predicate will be executed + * @return a `Future` which will hold the successful result of this `Future` if it matches the predicate or a `NoSuchElementException` */ final def withFilter(p: T => Boolean)(implicit executor: ExecutionContext): Future[T] = filter(p)(using executor) @@ -446,6 +448,7 @@ trait Future[+T] extends Awaitable[T] { * @tparam R the type of the resulting `Future` * @param that the other `Future` * @param f the function to apply to the results of `this` and `that` + * @param executor the `ExecutionContext` on which `f` will be executed * @return a `Future` with the result of the application of `f` to the results of `this` and `that` * @group Transformations */ @@ -749,6 +752,8 @@ object Future { * @tparam CC the type of the `IterableOnce` of Futures * @tparam To the type of the resulting collection * @param in the `IterableOnce` of Futures which will be sequenced + * @param bf the `BuildFrom` used to construct the resulting collection `To` from the values of type `A` + * @param executor the `ExecutionContext` on which the sequencing will be executed * @return the `Future` of the resulting collection */ final def sequence[A, CC[X] <: IterableOnce[X], To](in: CC[Future[A]])(implicit bf: BuildFrom[CC[Future[A]], A, To], executor: ExecutionContext): Future[To] = @@ -834,6 +839,8 @@ object Future { * @param zero the start value of the fold * @param op the fold operation to be applied to the zero and futures * @return the `Future` holding the result of the fold + * + * @param executor the `ExecutionContext` on which the fold operation will be executed */ final def foldLeft[T, R](futures: scala.collection.immutable.Iterable[Future[T]])(zero: R)(op: (R, T) => R)(implicit executor: ExecutionContext): Future[R] = foldNext(futures.iterator, zero, op) @@ -902,6 +909,8 @@ object Future { * @param futures the `scala.collection.immutable.Iterable` of Futures to be reduced * @param op the reduce operation which is applied to the results of the futures * @return the `Future` holding the result of the reduce + * + * @param executor the `ExecutionContext` on which the reduce operation will be executed */ final def reduceLeft[T, R >: T](futures: scala.collection.immutable.Iterable[Future[T]])(op: (R, T) => R)(implicit executor: ExecutionContext): Future[R] = { val i = futures.iterator @@ -926,6 +935,9 @@ object Future { * @param in the collection to be mapped over with the provided function to produce a collection of Futures that is then sequenced into a Future collection * @param fn the function to be mapped over the collection to produce a collection of Futures * @return the `Future` of the collection of results + * + * @param bf the `BuildFrom` used to construct the resulting collection `M[B]` from the values of type `B` + * @param executor the `ExecutionContext` on which `fn` and the resulting Futures will be executed */ final def traverse[A, B, M[X] <: IterableOnce[X]](in: M[A])(fn: A => Future[B])(implicit bf: BuildFrom[M[A], B, M[B]], executor: ExecutionContext): Future[M[B]] = in.iterator.foldLeft(successful(bf.newBuilder(in))) { diff --git a/library/src/scala/concurrent/SyncVar.scala b/library/src/scala/concurrent/SyncVar.scala index 33caf16b475d..4f51418372cf 100644 --- a/library/src/scala/concurrent/SyncVar.scala +++ b/library/src/scala/concurrent/SyncVar.scala @@ -39,6 +39,7 @@ class SyncVar[A] { * It never returns negative results. * * @param timeout the maximum time to wait, in milliseconds + * @return the elapsed wait time in milliseconds, or `0` if `timeout <= 0` or the elapsed time was negative */ private def waitMeasuringElapsed(timeout: Long): Long = if (timeout <= 0) 0 else { val start = System.nanoTime() diff --git a/library/src/scala/concurrent/duration/Deadline.scala b/library/src/scala/concurrent/duration/Deadline.scala index a079cf156c32..b9b210519884 100644 --- a/library/src/scala/concurrent/duration/Deadline.scala +++ b/library/src/scala/concurrent/duration/Deadline.scala @@ -71,6 +71,7 @@ case class Deadline private (time: FiniteDuration) extends Ordered[Deadline] { /** The natural ordering for deadline is determined by the natural order of the underlying (finite) duration. * * @param other the deadline to compare against + * @return a negative value if this deadline is earlier than `other`, zero if they are equal, or a positive value if this deadline is later */ def compare(other: Deadline): Int = time compare other.time } diff --git a/library/src/scala/concurrent/duration/Duration.scala b/library/src/scala/concurrent/duration/Duration.scala index 815266d20bc3..2ff9b33a441e 100644 --- a/library/src/scala/concurrent/duration/Duration.scala +++ b/library/src/scala/concurrent/duration/Duration.scala @@ -37,6 +37,7 @@ object Duration { * * @param length the duration length as a whole number * @param unit the time unit in which `length` is measured + * @return a finite duration of the given length in the given unit */ def apply(length: Long, unit: TimeUnit): FiniteDuration = new FiniteDuration(length, unit) @@ -61,6 +62,7 @@ object Duration { * Undefined is designated by `"Duration.Undefined"`. * * @param s the string to parse into a duration + * @return the duration represented by the string, possibly infinite or undefined * @throws NumberFormatException if format is not parsable */ def apply(s: String): Duration = { @@ -109,6 +111,7 @@ object Duration { * The extractor will not match for malformed strings or non-finite durations. * * @param s the string to parse and extract a length and time unit from + * @return `Some` pair of length and time unit if the string parses to a finite duration, `None` otherwise */ def unapply(s: String): Option[(Long, TimeUnit)] = ( try Some(apply(s)) catch { case _: RuntimeException => None } ) flatMap unapply @@ -116,6 +119,7 @@ object Duration { /** Extracts length and time unit out of a duration, if it is finite. * * @param d the duration to decompose into length and time unit + * @return `Some` pair of length and time unit if `d` is finite, `None` otherwise */ def unapply(d: Duration): Option[(Long, TimeUnit)] = if (d.isFinite) Some((d.length, d.unit)) else None @@ -157,6 +161,7 @@ object Duration { * this duration. * * @param nanos the number of nanoseconds + * @return a finite duration equal to `nanos` nanoseconds, expressed using the coarsest time unit that represents it exactly * @throws IllegalArgumentException for `Long.MinValue` since that would lead to inconsistent behavior afterwards (cannot be negated) */ def fromNanos(nanos: Long): FiniteDuration = { @@ -273,6 +278,7 @@ object Duration { * * @param length the duration length as a whole number * @param unit the time unit in which `length` is measured + * @return a finite duration of the given length in the given unit */ def create(length: Long, unit: TimeUnit): FiniteDuration = apply(length, unit) /** Constructs a Duration from the given length and unit. Observe that nanosecond precision may be lost if @@ -304,6 +310,7 @@ object Duration { * designated by `"Inf"`, `"PlusInf"`, `"+Inf"` and `"-Inf"` or `"MinusInf"`. * * @param s the string to parse into a duration + * @return the duration represented by the string, possibly infinite or undefined * @throws NumberFormatException if format is not parsable */ def create(s: String): Duration = apply(s) @@ -454,6 +461,7 @@ sealed abstract class Duration extends Serializable with Ordered[Duration] { * - [[Duration.MinusInf]] is mapped to Double.NegativeInfinity * * @param unit the time unit to convert to + * @return the length of this duration expressed in the given `unit` as a `Double` */ def toUnit(unit: TimeUnit): Double @@ -508,11 +516,13 @@ sealed abstract class Duration extends Serializable with Ordered[Duration] { /** Returns the smaller of this and that duration as determined by the natural ordering. * * @param other the duration to compare with + * @return the smaller of `this` and `other` */ def min(other: Duration): Duration = if (this < other) this else other /** Returns the larger of this and that duration as determined by the natural ordering. * * @param other the duration to compare with + * @return the larger of `this` and `other` */ def max(other: Duration): Duration = if (this > other) this else other @@ -531,6 +541,7 @@ sealed abstract class Duration extends Serializable with Ordered[Duration] { * determined by Double as if calculating the quotient of the nanosecond lengths of both factors. * * @param other the duration to divide by + * @return the quotient of this and `other` as a floating-point number */ def div(other: Duration): Double = this / other def gt(other: Duration): Boolean = this > other @@ -697,6 +708,7 @@ final class FiniteDuration(val length: Long, val unit: TimeUnit) extends Duratio /** Returns the quotient of this duration and the given integer factor. * * @param divisor the integer value to divide by + * @return this duration divided by the given divisor * @throws java.lang.ArithmeticException if the factor is 0 */ def /(divisor: Long): FiniteDuration = fromNanos(toNanos / divisor) @@ -731,6 +743,7 @@ final class FiniteDuration(val length: Long, val unit: TimeUnit) extends Duratio /** Returns the quotient of this duration and the given integer factor. * * @param divisor the integer value to divide by + * @return this duration divided by the given divisor * @throws java.lang.ArithmeticException if the factor is 0 */ def div(divisor: Long): FiniteDuration = this / divisor @@ -738,6 +751,7 @@ final class FiniteDuration(val length: Long, val unit: TimeUnit) extends Duratio /** Returns the product of this duration and the given integer factor. * * @param factor the integer value to multiply by + * @return this duration scaled by the given factor * @throws IllegalArgumentException if the result would overflow the range of FiniteDuration */ def mul(factor: Long): FiniteDuration = this * factor diff --git a/library/src/scala/concurrent/impl/Promise.scala b/library/src/scala/concurrent/impl/Promise.scala index e9c1eba11c0c..1551592923f1 100644 --- a/library/src/scala/concurrent/impl/Promise.scala +++ b/library/src/scala/concurrent/impl/Promise.scala @@ -68,6 +68,7 @@ private[concurrent] object Promise { /** Compresses this chain and returns the currently known root of this chain of Links. * * @param owner the `DefaultPromise` that owns this link, used to complete it if the root is already resolved + * @return the root `DefaultPromise` of the dependency chain, or `owner` (after completing it with the resolved value) if the chain has already been completed */ final def promise(owner: DefaultPromise[T]): DefaultPromise[T] = { val c = get() @@ -79,6 +80,7 @@ private[concurrent] object Promise { * @param current the `DefaultPromise` most recently read from this link's atomic reference * @param target the `DefaultPromise` currently being inspected while traversing the chain * @param owner the `DefaultPromise` that owns this link, used to complete it if the root is already resolved + * @return the root `DefaultPromise` reachable from `target`, or `owner` if the root was already completed */ @inline @tailrec private final def compressed(current: DefaultPromise[T], target: DefaultPromise[T], owner: DefaultPromise[T]): DefaultPromise[T] = { val value = target.get() @@ -98,6 +100,7 @@ private[concurrent] object Promise { * * @tparam T the type of the value contained in the `Try` * @param value the `Try` to resolve, must not be null + * @return the original `Try` for a `Success` or non-fatal `Failure`; a `Success` containing the extracted value when the failure is a `NonLocalReturnControl`; otherwise, for a fatal `ControlThrowable`, `InterruptedException`, or `Error`, a `Failure` wrapping the throwable in an `ExecutionException` */ // requireNonNull is paramount to guard against null completions private final def resolve[T](value: Try[T]): Try[T] = @@ -232,6 +235,7 @@ private[concurrent] object Promise { * @tparam U the result type of the callback function * @param func the callback function to invoke when the future completes * @param executor the `ExecutionContext` used to run the callback + * @return a function which, when invoked, unregisters the callback so it will not be called when this future completes */ private[concurrent] final def onCompleteWithUnregister[U](func: Try[T] => U)(implicit executor: ExecutionContext): () => Unit = { val t = new Transformation[T, Unit](Xform_onComplete, func, executor) @@ -332,6 +336,9 @@ private[concurrent] object Promise { * to the root promise when linking two promises together. * * @tparam C the specific subtype of `Callbacks[T]` being dispatched or added + * @param state the current state of this promise's atomic reference, as previously read by the caller + * @param callbacks the callbacks to dispatch immediately if this promise is already completed, or to add to the pending list otherwise + * @return the `callbacks` argument, returned unchanged to allow chaining */ @tailrec private final def dispatchOrAddCallbacks[C <: Callbacks[T]](state: AnyRef, callbacks: C): C = if (state.isInstanceOf[Try[?]]) { diff --git a/library/src/scala/runtime/FunctionXXL.scala b/library/src/scala/runtime/FunctionXXL.scala index 0117db7b873d..9f8fdc264651 100644 --- a/library/src/scala/runtime/FunctionXXL.scala +++ b/library/src/scala/runtime/FunctionXXL.scala @@ -8,6 +8,7 @@ trait FunctionXXL { /** Applies all parameters grouped in xs to this function. * * @param xs the function arguments, packed into an immutable array of `Object` + * @return the result of applying this function to the given arguments */ def apply(xs: IArray[Object]): Object diff --git a/library/src/scala/runtime/MethodCache.scala b/library/src/scala/runtime/MethodCache.scala index e0b81bf98572..8f2692979df8 100644 --- a/library/src/scala/runtime/MethodCache.scala +++ b/library/src/scala/runtime/MethodCache.scala @@ -35,6 +35,7 @@ private[scala] sealed abstract class MethodCache { * the cache for later use. * * @param forReceiver the runtime `Class` of the receiver object to look up in the cache + * @return the cached `JMethod` compatible with `forReceiver`, or `null` if no such method is cached (in which case the caller should look up the method and `add` it) */ def find(forReceiver: JClass[?]): JMethod | Null def add(forReceiver: JClass[?], forMethod: JMethod): MethodCache @@ -72,6 +73,7 @@ private[scala] final class PolyMethodCache( * from `find`, because the type of next is not `PolyMethodCache`. * * @param forReceiver the runtime `Class` of the receiver object to look up in the cache chain via tail recursion + * @return the cached `JMethod` whose receiver class is reference-equal to `forReceiver` anywhere in this chain, or `null` if no match exists */ @tailrec private def findInternal(forReceiver: JClass[?]): JMethod | Null = if (forReceiver eq receiver) method diff --git a/library/src/scala/runtime/stdLibPatches/Predef.scala b/library/src/scala/runtime/stdLibPatches/Predef.scala index 3284bdd3a00a..b42b83e4f3d8 100644 --- a/library/src/scala/runtime/stdLibPatches/Predef.scala +++ b/library/src/scala/runtime/stdLibPatches/Predef.scala @@ -68,6 +68,7 @@ private[scala] object Predef: * `eq` or `ne` methods, only `==` and `!=` inherited from `Any`. * * @param y the reference to compare against for referential equality + * @return `true` if `x` and `y` are the same reference (including both being `null`), `false` otherwise */ inline infix def eq(inline y: AnyRef | Null): Boolean = x.asInstanceOf[AnyRef] eq y.asInstanceOf[AnyRef] @@ -76,6 +77,7 @@ private[scala] object Predef: * `eq` or `ne` methods, only `==` and `!=` inherited from `Any`. * * @param y the reference to compare against for referential inequality + * @return `true` if `x` and `y` are not the same reference, `false` otherwise */ inline infix def ne(inline y: AnyRef | Null): Boolean = !(x eq y) diff --git a/library/src/scala/sys/BooleanProp.scala b/library/src/scala/sys/BooleanProp.scala index 0eb055940fac..0a09f7b50d0c 100644 --- a/library/src/scala/sys/BooleanProp.scala +++ b/library/src/scala/sys/BooleanProp.scala @@ -88,6 +88,7 @@ object BooleanProp { * * @param key the name of the system property * @param isOn whether the constant property is true or false + * @return a BooleanProp whose value is fixed and whose mutating operations are no-ops */ def constant(key: String, isOn: Boolean): BooleanProp = new ConstantImpl(key, isOn) diff --git a/library/src/scala/sys/Prop.scala b/library/src/scala/sys/Prop.scala index 3cb3e658afb7..26536056f2aa 100644 --- a/library/src/scala/sys/Prop.scala +++ b/library/src/scala/sys/Prop.scala @@ -69,6 +69,7 @@ trait Prop[+T] { * * @tparam T1 a supertype of `T`, the result type * @param alt the alternative value to use if the property is not set + * @return the property value if set, otherwise `alt` */ //def or[T1 >: T](alt: => T1): T1 @@ -92,6 +93,7 @@ object Prop { /** Creates a Prop[T] of this type based on the given key. * * @param key the property name used for lookup + * @return a new `Prop[T]` backed by the given key */ def apply(key: String): Prop[T] } diff --git a/library/src/scala/sys/ShutdownHookThread.scala b/library/src/scala/sys/ShutdownHookThread.scala index d894e119fd66..cbcedeb00256 100644 --- a/library/src/scala/sys/ShutdownHookThread.scala +++ b/library/src/scala/sys/ShutdownHookThread.scala @@ -32,6 +32,7 @@ object ShutdownHookThread { * given code. * * @param body the code to execute when the JVM shuts down + * @return the newly created and registered `ShutdownHookThread` */ def apply(body: => Unit): ShutdownHookThread = { val t = new ShutdownHookThread(() => body, hookName()) diff --git a/library/src/scala/sys/SystemProperties.scala b/library/src/scala/sys/SystemProperties.scala index d2378a0f2f94..93b6a64a8905 100644 --- a/library/src/scala/sys/SystemProperties.scala +++ b/library/src/scala/sys/SystemProperties.scala @@ -70,6 +70,7 @@ object SystemProperties { * * @tparam T the return type of the body expression * @param body the code to execute while holding the lock + * @return the result of evaluating `body` while holding the lock */ def exclusively[T](body: => T): T = this.synchronized: body diff --git a/library/src/scala/sys/process/BasicIO.scala b/library/src/scala/sys/process/BasicIO.scala index 260ef6e1e149..bb718909219c 100644 --- a/library/src/scala/sys/process/BasicIO.scala +++ b/library/src/scala/sys/process/BasicIO.scala @@ -231,6 +231,7 @@ object BasicIO { * [[scala.sys.process.ProcessIO]]. * * @param connect if true, stdin is connected to the process input; if false, the process input stream is not connected + * @return a sentinel function `OutputStream => Unit` for use with `ProcessIO`: when `connect` is true, the returned `connectToStdIn` value signals `ProcessBuilderImpl` to redirect stdin to the process input; otherwise `connectNoOp` signals it to leave the process input alone */ def input(connect: Boolean): OutputStream => Unit = if (connect) connectToStdIn else connectNoOp @@ -243,12 +244,14 @@ object BasicIO { /** Returns a `ProcessIO` connected to stdout and stderr, and, optionally, stdin. * * @param connectInput if true, stdin is connected to the process input + * @return a `ProcessIO` that writes the process's stdout to stdout and its stderr to stderr, and, when `connectInput` is true, also forwards stdin to the process input */ def standard(connectInput: Boolean): ProcessIO = standard(input(connectInput)) /** Returns a `ProcessIO` connected to stdout, stderr and the provided `in`. * * @param in a function to handle the process input stream + * @return a `ProcessIO` that delegates the process input to `in` and writes the process's stdout to stdout and its stderr to stderr */ def standard(in: OutputStream => Unit): ProcessIO = new ProcessIO(in, toStdOut, toStdErr) diff --git a/library/src/scala/sys/process/ProcessBuilder.scala b/library/src/scala/sys/process/ProcessBuilder.scala index 79331158c975..8c611b03a15c 100644 --- a/library/src/scala/sys/process/ProcessBuilder.scala +++ b/library/src/scala/sys/process/ProcessBuilder.scala @@ -184,6 +184,7 @@ trait ProcessBuilder extends Source with Sink { * and then throw an exception. * * @param capacity the maximum number of lines to buffer before blocking the producer + * @return a `LazyList` of the process's standard output lines that throws an exception after yielding all lines if the exit code is non-zero */ def lazyLines(capacity: Integer): LazyList[String] @@ -194,6 +195,7 @@ trait ProcessBuilder extends Source with Sink { * to termination and then throw an exception. * * @param log the `ProcessLogger` to receive standard error output + * @return a `LazyList` of the process's standard output lines that throws an exception after yielding all lines if the exit code is non-zero */ def lazyLines(log: ProcessLogger): LazyList[String] @@ -208,6 +210,7 @@ trait ProcessBuilder extends Source with Sink { * * @param log the `ProcessLogger` to receive standard error output * @param capacity the maximum number of lines to buffer before blocking the producer + * @return a `LazyList` of the process's standard output lines that throws an exception after yielding all lines if the exit code is non-zero */ def lazyLines(log: ProcessLogger, capacity: Integer): LazyList[String] diff --git a/library/src/scala/sys/process/ProcessLogger.scala b/library/src/scala/sys/process/ProcessLogger.scala index d7f1fb26fb24..48115a58cd7b 100644 --- a/library/src/scala/sys/process/ProcessLogger.scala +++ b/library/src/scala/sys/process/ProcessLogger.scala @@ -62,6 +62,7 @@ trait ProcessLogger { * * @tparam T the return type of the buffered operation * @param f the code to execute with buffering, evaluated by name + * @return the result produced by evaluating `f` */ def buffer[T](f: => T): T }