(3) core array, function, tuple, sys: Add Scaladoc for undocumented entities

library/src/scala/Array.scala

@@ -55,7 +55,13 @@ object Array {
   implicit def toFactory[A : ClassTag](dummy: Array.type): Factory[A, Array[A]] = new ArrayFactory(dummy)
   @SerialVersionUID(3L)
   private class ArrayFactory[A : ClassTag](dummy: Array.type) extends Factory[A, Array[A]] with Serializable {
+    /** Builds an array containing the elements of the given collection.
+     *
+     *  @param it the source of elements to include in the array
+     *  @return a new `Array[A]` holding the elements of `it`, in iteration order
+     */
     def fromSpecific(it: IterableOnce[A]^): Array[A] = Array.from[A](it)
+    /** Returns a new builder that accumulates elements into an `Array[A]`. */
     def newBuilder: mutable.Builder[A, Array[A]] = Array.newBuilder[A]
   }
 
@@ -704,12 +710,47 @@ object Array {
    */
   def unapplySeq[T](x: Array[T]): UnapplySeqWrapper[T] = new UnapplySeqWrapper(x)
 
+  /** A wrapper that lets an array be destructured by a sequence pattern such as
+   *  `case Array(x, y, z) =>`.
+   *
+   *  The members below implement the name-based extractor protocol directly against
+   *  the wrapped array, so a fixed-arity pattern matches without building an
+   *  intermediate sequence.
+   *
+   *  @tparam T the element type of the wrapped array
+   *  @param a the array to be destructured
+   */
   final class UnapplySeqWrapper[T](private val a: Array[T]) extends AnyVal {
+    /** Returns `false`, since this extractor never yields an empty result.
+     *
+     *  The literal type `false` tells the compiler that the extraction itself cannot fail, so
+     *  [[get]] is always available. Whether a particular sequence pattern matches is decided
+     *  separately, by [[lengthCompare]] and the element accessors.
+     */
     def isEmpty: false = false
+    /** Returns this wrapper, whose sequence-like operations supply the elements of the pattern. */
     def get: UnapplySeqWrapper[T] = this
+    /** Compares the length of the wrapped array to a test value.
+     *
+     *  @param len the test value that gets compared with the length
+     *  @return a value less than, equal to, or greater than `0` as the length of the array is less than, equal to, or greater than `len`
+     */
     def lengthCompare(len: Int): Int = a.lengthCompare(len)
+    /** Returns the element of the wrapped array at the given index.
+     *
+     *  @param i the index, which must be in the range from `0` until the length of the array
+     *  @return the element at index `i`
+     *  @throws ArrayIndexOutOfBoundsException if `i < 0` or the length of the wrapped array `<= i`
+     */
     def apply(i: Int): T = a(i)
+    /** Returns all elements of the wrapped array except the first `n`, as needed to bind the
+     *  variable-length part of a pattern such as `case Array(x, rest*) =>`.
+     *
+     *  @param n the number of leading elements to skip
+     *  @return a sequence backed by a fresh copy of the remaining elements, even when `n` is `0`
+     */
     def drop(n: Int): scala.Seq[T] = ArraySeq.unsafeWrapArray(a.drop(n)) // clones the array, also if n == 0
+    /** Returns the elements of the wrapped array as a sequence backed by a copy of the array. */
     def toSeq: scala.Seq[T] = a.toSeq // clones the array
   }
 }

library/src/scala/Function0.scala

@@ -37,5 +37,6 @@ trait Function0[@specialized(Specializable.Primitives) +R] extends AnyRef {
    */
   def apply(): R
 
+  /** Returns the string `"<function0>"`. */
   override def toString(): String = "<function0>"
 }

library/src/scala/Function1.scala

@@ -16,6 +16,11 @@ import scala.language.`2.13`
 
 object Function1 {
 
+  /** Provides the [[UnliftOps.unlift]] method on functions that return an [[scala.Option]].
+   *
+   *  @tparam A the argument type of the wrapped function
+   *  @tparam B the type of the value contained in the `Option` result of the wrapped function
+   */
   implicit final class UnliftOps[A, B] private[Function1](private val f: A => Option[B]) extends AnyVal {
     /** Converts an optional function to a partial function.
      *
@@ -87,5 +92,6 @@ trait Function1[@specialized(Specializable.Arg) -T1, @specialized(Specializable.
    */
   @annotation.unspecialized def andThen[A](g: R => A): T1 => A = { x => g(apply(x)) }
 
+  /** Returns the string `"<function1>"`. */
   override def toString(): String = "<function1>"
 }

library/src/scala/Function10.scala

@@ -60,5 +60,6 @@ trait Function10[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, +R] extends
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10)
   }
+  /** Returns the string `"<function10>"`. */
   override def toString(): String = "<function10>"
 }

library/src/scala/Function11.scala

@@ -62,5 +62,6 @@ trait Function11[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, +R] ex
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11)
   }
+  /** Returns the string `"<function11>"`. */
   override def toString(): String = "<function11>"
 }

library/src/scala/Function12.scala

@@ -64,5 +64,6 @@ trait Function12[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12)
   }
+  /** Returns the string `"<function12>"`. */
   override def toString(): String = "<function12>"
 }

library/src/scala/Function13.scala

@@ -66,5 +66,6 @@ trait Function13[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13)
   }
+  /** Returns the string `"<function13>"`. */
   override def toString(): String = "<function13>"
 }

library/src/scala/Function14.scala

@@ -68,5 +68,6 @@ trait Function14[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14)
   }
+  /** Returns the string `"<function14>"`. */
   override def toString(): String = "<function14>"
 }

library/src/scala/Function15.scala

@@ -70,5 +70,6 @@ trait Function15[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15)
   }
+  /** Returns the string `"<function15>"`. */
   override def toString(): String = "<function15>"
 }

library/src/scala/Function16.scala

@@ -72,5 +72,6 @@ trait Function16[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16)
   }
+  /** Returns the string `"<function16>"`. */
   override def toString(): String = "<function16>"
 }

library/src/scala/Function17.scala

@@ -74,5 +74,6 @@ trait Function17[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17)
   }
+  /** Returns the string `"<function17>"`. */
   override def toString(): String = "<function17>"
 }

library/src/scala/Function18.scala

@@ -76,5 +76,6 @@ trait Function18[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17, x18)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17, x18)
   }
+  /** Returns the string `"<function18>"`. */
   override def toString(): String = "<function18>"
 }

library/src/scala/Function19.scala

@@ -78,5 +78,6 @@ trait Function19[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18, T19)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17, x18, x19)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17, x18, x19)
   }
+  /** Returns the string `"<function19>"`. */
   override def toString(): String = "<function19>"
 }

library/src/scala/Function2.scala

@@ -54,5 +54,6 @@ trait Function2[@specialized(Specializable.Args) -T1, @specialized(Specializable
   @annotation.unspecialized def tupled: ((T1, T2)) => R = {
     case ((x1, x2)) => apply(x1, x2)
   }
+  /** Returns the string `"<function2>"`. */
   override def toString(): String = "<function2>"
 }

library/src/scala/Function20.scala

@@ -80,5 +80,6 @@ trait Function20[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18, T19, T20)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17, x18, x19, x20)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17, x18, x19, x20)
   }
+  /** Returns the string `"<function20>"`. */
   override def toString(): String = "<function20>"
 }

library/src/scala/Function21.scala

@@ -82,5 +82,6 @@ trait Function21[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18, T19, T20, T21)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17, x18, x19, x20, x21)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17, x18, x19, x20, x21)
   }
+  /** Returns the string `"<function21>"`. */
   override def toString(): String = "<function21>"
 }

library/src/scala/Function22.scala

@@ -84,5 +84,6 @@ trait Function22[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, -T10, -T11, -T12,
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16, T17, T18, T19, T20, T21, T22)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17, x18, x19, x20, x21, x22)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15, x16, x17, x18, x19, x20, x21, x22)
   }
+  /** Returns the string `"<function22>"`. */
   override def toString(): String = "<function22>"
 }

library/src/scala/Function3.scala

@@ -46,5 +46,6 @@ trait Function3[-T1, -T2, -T3, +R] extends AnyRef {
   @annotation.unspecialized def tupled: ((T1, T2, T3)) => R = {
     case ((x1, x2, x3)) => apply(x1, x2, x3)
   }
+  /** Returns the string `"<function3>"`. */
   override def toString(): String = "<function3>"
 }

library/src/scala/Function4.scala

@@ -48,5 +48,6 @@ trait Function4[-T1, -T2, -T3, -T4, +R] extends AnyRef {
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4)) => R = {
     case ((x1, x2, x3, x4)) => apply(x1, x2, x3, x4)
   }
+  /** Returns the string `"<function4>"`. */
   override def toString(): String = "<function4>"
 }

library/src/scala/Function5.scala

@@ -50,5 +50,6 @@ trait Function5[-T1, -T2, -T3, -T4, -T5, +R] extends AnyRef {
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5)) => R = {
     case ((x1, x2, x3, x4, x5)) => apply(x1, x2, x3, x4, x5)
   }
+  /** Returns the string `"<function5>"`. */
   override def toString(): String = "<function5>"
 }

library/src/scala/Function6.scala

@@ -52,5 +52,6 @@ trait Function6[-T1, -T2, -T3, -T4, -T5, -T6, +R] extends AnyRef {
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6)) => R = {
     case ((x1, x2, x3, x4, x5, x6)) => apply(x1, x2, x3, x4, x5, x6)
   }
+  /** Returns the string `"<function6>"`. */
   override def toString(): String = "<function6>"
 }

library/src/scala/Function7.scala

@@ -54,5 +54,6 @@ trait Function7[-T1, -T2, -T3, -T4, -T5, -T6, -T7, +R] extends AnyRef {
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7)) => apply(x1, x2, x3, x4, x5, x6, x7)
   }
+  /** TODO FILL IN */
   override def toString(): String = "<function7>"
 }

library/src/scala/Function8.scala

@@ -56,5 +56,6 @@ trait Function8[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, +R] extends AnyRef {
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8)) => apply(x1, x2, x3, x4, x5, x6, x7, x8)
   }
+  /** Returns the string `"<function8>"`. */
   override def toString(): String = "<function8>"
 }

library/src/scala/Function9.scala

@@ -58,5 +58,6 @@ trait Function9[-T1, -T2, -T3, -T4, -T5, -T6, -T7, -T8, -T9, +R] extends AnyRef
   @annotation.unspecialized def tupled: ((T1, T2, T3, T4, T5, T6, T7, T8, T9)) => R = {
     case ((x1, x2, x3, x4, x5, x6, x7, x8, x9)) => apply(x1, x2, x3, x4, x5, x6, x7, x8, x9)
   }
+  /** Returns the string `"<function9>"`. */
   override def toString(): String = "<function9>"
 }

library/src/scala/IArray.scala

@@ -740,6 +740,12 @@ object IArray:
   def from[A : ClassTag](it: IterableOnce[A]^): IArray[A] =
     unsafeFromArray(Array.from(it))
 
+  /** Returns a new empty builder for immutable arrays of element type `T`.
+   *
+   *  @tparam T the element type of the array
+   *  @param t the `ClassTag` for the element type `T`, used to allocate the underlying array
+   *  @return  a new builder that produces an `IArray[T]` from the elements added to it
+   */
   def newBuilder[T](using t: ClassTag[T]): Builder[T, IArray[T]] =
     ArrayBuilder.make[T].mapResult(IArray.unsafeFromArray)
 
@@ -995,6 +1001,21 @@ object IArray:
       b.result()
     }
 
+    /** Builds a new array by applying a function to each element of this array
+     *  that satisfies this filter's predicate and using the elements of the
+     *  resulting collections.
+     *
+     *  Unlike the overload taking an `IterableOnce`-valued function, `f` may return
+     *  any type that can be viewed as an `Iterable[U]`.
+     *
+     *  @tparam BS the result type of `f`, which must be viewable as an `Iterable[U]`.
+     *  @tparam U the element type of the returned array.
+     *  @param f the function to apply to each element.
+     *  @param asIterable the implicit conversion viewing the result of `f` as an `Iterable[U]`.
+     *  @param m the `ClassTag` for the returned array's element type `U`.
+     *  @return a new array resulting from applying `f` to each element of this array
+     *          that satisfies the filter predicate and concatenating the results.
+     */
     def flatMap[BS, U](f: T => BS)(using asIterable: BS => Iterable[U]^, m: ClassTag[U]): IArray[U] =
       flatMap[U](x => asIterable(f(x)))
 

library/src/scala/Option.scala

@@ -164,6 +164,11 @@ object Option {
  *  @tparam A the type of the value contained in the option
  */
 @SerialVersionUID(-114498752079829388L) // value computed by serialver for 2.11.2, annotation added in 2.11.4
+/** Represents optional values. Instances of `Option` are either an instance
+ *  of [[scala.Some]] or the object `None`.
+ *
+ *  @tparam A the type of the value contained in the option
+ */
 sealed abstract class Option[+A] extends IterableOnce[A] with Product with Serializable {
   self =>
 
@@ -195,6 +200,7 @@ sealed abstract class Option[+A] extends IterableOnce[A] with Product with Seria
    */
   final def isDefined: Boolean = !isEmpty
 
+  /** Returns the number of elements this option contains: 0 if it is $none, 1 otherwise. */
   override final def knownSize: Int = if (isEmpty) 0 else 1
 
   /** Returns the option's value.
@@ -411,9 +417,37 @@ sealed abstract class Option[+A] extends IterableOnce[A] with Product with Seria
    *  @param p the predicate used to filter the option value
    */
   class WithFilter(p: A => Boolean) {
+    /** Returns a $some containing the result of applying $f to the filtered
+     *  $option's value, or $none if the $option is empty or its value does not
+     *  satisfy $p.
+     *
+     *  @tparam B the result type of the function `f`
+     *  @param f the function to apply
+     *  @return a `Some` containing `f` applied to the option's value if the option
+     *          is nonempty and its value satisfies `p`, otherwise `None`
+     */
     def map[B](f: A => B): Option[B] = self filter p map f
+    /** Returns the result of applying $f to the filtered $option's value, or
+     *  $none if the $option is empty or its value does not satisfy $p.
+     *
+     *  @tparam B the element type of the returned option
+     *  @param f the function to apply
+     *  @return the result of applying `f` to the option's value if the option is
+     *          nonempty and its value satisfies `p`, otherwise `None`
+     */
     def flatMap[B](f: A => Option[B]): Option[B] = self filter p flatMap f
+    /** Applies the given procedure $f to the filtered $option's value, if the
+     *  $option is nonempty and its value satisfies $p. Otherwise, does nothing.
+     *
+     *  @tparam U the result type of the procedure `f` (result is discarded)
+     *  @param f the procedure to apply
+     */
     def foreach[U](f: A => U): Unit = self filter p foreach f
+    /** Returns a `WithFilter` whose predicate is the conjunction of $p and `q`.
+     *
+     *  @param q the additional predicate used to test the option's value
+     *  @return a `WithFilter` whose predicate holds only when both `p` and `q` hold
+     */
     def withFilter(q: A => Boolean): WithFilter = new WithFilter(x => p(x) && q(x))
   }
 
@@ -692,13 +726,20 @@ sealed abstract class Option[+A] extends IterableOnce[A] with Product with Seria
  *  @param value the contained value
  */
 @SerialVersionUID(1234815782226070388L) // value computed by serialver for 2.11.2, annotation added in 2.11.4
+/** Represents an existing value of type `A`.
+ *
+ *  @tparam A the type of the contained value
+ *  @param value the contained value
+ */
 final case class Some[+A](value: A) extends Option[A] {
+  /** Returns the contained value. */
   def get: A = value
 }
 
 
 /** This case object represents non-existent values. */
 @SerialVersionUID(5066590221178148012L) // value computed by serialver for 2.11.2, annotation added in 2.11.4
 case object None extends Option[Nothing] {
+  /** Throws a `NoSuchElementException`, since `None` holds no value. */
   def get: Nothing = throw new NoSuchElementException("None.get")
 }