Sys, concurrent, runtime (1): filled in @param, @tparam, and @return tags that were missed last time

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

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))) {

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()

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
 }

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,13 +111,15 @@ 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
 
   /** 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,13 +743,15 @@ 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
 
   /** 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

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[?]]) {

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
 

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

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)

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)
 

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]
   }

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())

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

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)
 

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]