Correct the added Scaladoc where it did not match the implementation

Adjudicated from an independent review of this branch. Comment-only.

- LazyVals.LazyValControlState was described as a state held only while a lazy
  val is unbound. NullValue is the permanent sentinel for a lazy val that
  evaluated to null, so it outlives the computation.
- ModuleSerializationProxy said the resolved instance is cached per class. It
  is, through ClassValue, but the ClassValueCompat fallback recomputes on every
  access where java.lang.ClassValue is unavailable.
- ArrayCharSequence.charAt can also throw for a slice whose bounds fall outside
  the array, since the constructor does not validate them, and toString takes
  its count from the declared bounds, so a negative start shifts the window
  rather than clipping it.
- ScalaRunTime.isArray described atLevel as a minimum; below 1 it never holds.
  stringOf's maxElements renders nothing at all below 1.
- StructuralCallSite.find can throw NoSuchMethodException from the reflective
  lookup a mega-morphic cache performs, and add records nothing and leaves the
  cache alone once the site is mega-morphic.
- IntegralProxy.until and to documented only the zero-step failure; the same
  deferred length computation also throws for a range of more than Int.MaxValue
  elements.
- Tuples.productToArray is called for arities 1 to 22; the empty tuple is
  handled separately with Array.emptyObjectArray.
- VarArgsBuilder.result returns a sequence over the whole fixed-length array
  rather than only the elements added, and its n parameter is an allocation
  length that nothing enforces.

Twenty-nine @return tags that merely restated a summary already beginning with
"Returns" or "Creates" are removed, across TupledFunctions, TupleXXL,
TupleMirror and the two Zipped iterables. The project's convention is to drop a
@return in exactly that case.

Declined: documenting, on each scala.runtime.java8 specialisation bridge, that
unboxing null yields a zero and that a wrongly typed argument throws
ClassCastException. Both are true of BoxesRunTime generally, these bridges are
compiler-facing rather than called directly, and there are hundreds of them.

Author: bvenners

library/src/scala/runtime/ArrayCharSequence.scala

@@ -43,8 +43,10 @@ final class ArrayCharSequence(val xs: Array[Char], start: Int, end: Int) extends
    *
    *  @param index the index of the character to return, from `0` to `length - 1`
    *  @throws ArrayIndexOutOfBoundsException if `index` is negative or not less
-   *          than `length` (the exception message reports the bounds of the
-   *          underlying array, not of this sequence)
+   *          than `length`, or if the slice this sequence was constructed with
+   *          falls outside the array, since those bounds are not validated (the
+   *          exception message reports the bounds of the underlying array, not
+   *          of this sequence)
    */
   def charAt(index: Int): Char = {
     if (0 <= index && index < length)
@@ -78,8 +80,10 @@ final class ArrayCharSequence(val xs: Array[Char], start: Int, end: Int) extends
    *
    *  The bounds are clamped to the underlying array before copying: a
    *  negative `start` is treated as `0` and the end is capped at the array's
-   *  length, so a sequence constructed with out-of-range bounds yields its
-   *  in-range characters (or the empty string) rather than throwing.
+   *  length, so a sequence constructed with out-of-range bounds yields
+   *  characters rather than throwing. The count is taken from the declared
+   *  bounds, so a negative `start` shifts the window: `start = -2, end = 5`
+   *  copies seven characters from index `0`, not the five in range.
    */
   override def toString() = {
     val start = math.max(this.start, 0)

library/src/scala/runtime/LazyVals.scala

@@ -48,9 +48,10 @@ object LazyVals {
   /* ------------- Start of public API ------------- */
 
   // This trait extends Serializable to fix #16806 that caused a race condition
-  /** A control state stored in the field of a lazy val while the val is not
-   *  yet bound to its computed value: [[Evaluating]], a [[Waiting]] latch,
-   *  or [[NullValue]].
+  /** A state stored in the field of a lazy val other than an ordinary computed value:
+   *  [[Evaluating]] or a [[Waiting]] latch while the val is not yet bound, and
+   *  [[NullValue]], which is the permanent sentinel for a lazy val that evaluated to
+   *  `null`.
    *
    *  Extends `Serializable` so that an object can be serialized while one of
    *  its lazy vals holds a control state (issue #16806).

library/src/scala/runtime/ModuleSerializationProxy.scala

@@ -44,8 +44,9 @@ private[runtime] object ModuleSerializationProxy {
  *  method that serializes an instance of this class instead of the object
  *  itself. On deserialization, `readResolve` replaces the proxy with the
  *  object's unique instance, obtained reflectively from the `MODULE$` field
- *  of `moduleClass` (and cached per class), so deserialization yields the
- *  singleton rather than a fresh copy.
+ *  of `moduleClass`, so deserialization yields the singleton rather than a
+ *  fresh copy. The lookup is cached per class where `java.lang.ClassValue` is
+ *  available, and repeated on each deserialization where it is not.
  *
  *  @param moduleClass the class of the object whose instance the proxy
  *                     resolves to

library/src/scala/runtime/ScalaNumberProxy.scala

@@ -106,8 +106,9 @@ trait IntegralProxy[T] extends Any with ScalaWholeNumberProxy[T] with RangedProx
    *  @param step the increment between consecutive elements; may be negative
    *  @return an exclusive [[scala.collection.immutable.NumericRange]] from this
    *          value until `end` with the given step
-   *  @throws IllegalArgumentException if `step` is zero (thrown when the
-   *          range's length is first computed)
+   *  @throws IllegalArgumentException if `step` is zero, or if the range has more
+   *          than `Int.MaxValue` elements; both are raised when the range's length
+   *          is first computed, not when it is constructed
    */
   def until(end: T, step: T): NumericRange.Exclusive[T] = NumericRange(self, end, step)
   /** Returns a range from the wrapped value up to and including `end`, in
@@ -125,8 +126,9 @@ trait IntegralProxy[T] extends Any with ScalaWholeNumberProxy[T] with RangedProx
    *  @param step the increment between consecutive elements; may be negative
    *  @return an inclusive [[scala.collection.immutable.NumericRange]] from this
    *          value to `end` with the given step
-   *  @throws IllegalArgumentException if `step` is zero (thrown when the
-   *          range's length is first computed)
+   *  @throws IllegalArgumentException if `step` is zero, or if the range has more
+   *          than `Int.MaxValue` elements; both are raised when the range's length
+   *          is first computed, not when it is constructed
    */
   def to(end: T, step: T): NumericRange.Inclusive[T]    = NumericRange.inclusive(self, end, step)
 }

library/src/scala/runtime/ScalaRunTime.scala

@@ -31,7 +31,9 @@ object ScalaRunTime {
   /** Tests whether `x` is an array with at least `atLevel` dimensions.
    *
    *  @param x the value to test; `null` yields `false`
-   *  @param atLevel the minimum number of array dimensions required; the default, 1, accepts any array
+   *  @param atLevel the number of array dimensions required; a value below 1 never
+   *                 holds, since the check descends one component type per level and
+   *                 fails once it reaches a non-array; the default, 1, accepts any array
    *  @return `true` if `x` is a non-null array of at least `atLevel` dimensions, `false` otherwise
    */
   def isArray(x: Any, atLevel: Int = 1): Boolean =
@@ -289,7 +291,8 @@ object ScalaRunTime {
    *  back to `String.valueOf(arg)`.
    *
    *  @param arg the value to stringify
-   *  @param maxElements the maximum number of elements rendered per collection or array
+   *  @param maxElements the maximum number of elements rendered per collection or array;
+   *                     a value below 1 renders none of them
    */
   def stringOf(arg: Any, maxElements: Int): String = {
     def packageOf(x: AnyRef) = x.getClass.getPackage match {

library/src/scala/runtime/StructuralCallSite.scala

@@ -52,12 +52,16 @@ final class StructuralCallSite private (callType: MethodType) {
    *  per-receiver entries; see [[MethodCache.find]].
    *
    *  @param receiver the runtime `Class` of the receiver object
+   *  @throws NoSuchMethodException from the reflective lookup a mega-morphic cache
+   *          performs, in place of returning `null`
    */
   def find(receiver: Class[?]): Method | Null = get.find(receiver)
 
   /** Records that `m` is the method to call for receiver class `receiver`,
-   *  replacing this call site's cache with the extended one, and returns
-   *  `m`.
+   *  replacing this call site's cache with the extended one, and returns `m`.
+   *
+   *  Once the cache has turned mega-morphic it records nothing per receiver and
+   *  returns itself, so the call site's cache is then left as it was.
    *
    *  @param receiver the runtime `Class` of the receiver object
    *  @param m the method resolved for `receiver`

library/src/scala/runtime/TupleXXL.scala

@@ -41,7 +41,6 @@ final class TupleXXL private (es: IArray[Object]) extends Product {
   /** Returns whether `that` can be compared for equality against this tuple.
    *
    *  @param that the value to test
-   *  @return `true` if `that` is a `TupleXXL` with the same arity as this tuple, `false` otherwise
    */
   override def canEqual(that: Any): Boolean = that match {
     case that: TupleXXL => that.productArity == this.productArity
@@ -56,7 +55,6 @@ final class TupleXXL private (es: IArray[Object]) extends Product {
    *  a `TupleXXL` is never equal to this tuple.
    *
    *  @param that the value to compare against
-   *  @return `true` if `that` is a `TupleXXL` equal to this tuple, `false` otherwise
    */
   override def equals(that: Any): Boolean = that match {
     case that: TupleXXL =>
@@ -95,19 +93,16 @@ object TupleXXL {
    *  The iterator is fully consumed into a fresh array.
    *
    *  @param elems the iterator supplying the elements; must produce more than 22 values (asserted)
-   *  @return a `TupleXXL` with the produced values as its elements
    */
   def fromIterator(elems: Iterator[Any]): TupleXXL = new TupleXXL(elems.map(_.asInstanceOf[Object]).toArray.asInstanceOf[IArray[Object]]) // TODO use Iterator.toIArray
   /** Creates a `TupleXXL` backed directly by `elems`; the array is not copied.
    *
    *  @param elems the immutable array to use as the tuple's backing storage; must have more than 22 elements (asserted)
-   *  @return a `TupleXXL` whose elements are those of `elems`
    */
   def fromIArray(elems: IArray[Object]): TupleXXL = new TupleXXL(elems)
   /** Creates a `TupleXXL` with the given elements.
    *
    *  @param elems the elements of the tuple; more than 22 must be supplied (asserted)
-   *  @return a `TupleXXL` with the given elements, in order
    */
   def apply(elems: Any*): TupleXXL = new TupleXXL(IArray(elems.asInstanceOf[Seq[AnyRef]]*))
   /** Extracts the elements of a `TupleXXL`, enabling `case TupleXXL(xs*)` patterns.