Merge pull request #10605 from som-snytt/issue/12904-api-doc

Add or improve library doc [ci: last-only]

build.sbt

@@ -418,7 +418,8 @@ lazy val library = configureAsSubproject(project)
       Seq(
         "-doc-no-compile", libraryAuxDir.toString,
         "-skip-packages", "scala.concurrent.impl",
-        "-doc-root-content", (Compile / sourceDirectory).value + "/rootdoc.txt"
+        "-doc-root-content", (Compile / sourceDirectory).value + "/rootdoc.txt",
+        //"-required", // placeholder for internal flag
       )
     },
     Compile / console / scalacOptions := {

src/library/scala/collection/IterableOnce.scala

@@ -401,7 +401,7 @@ trait IterableOnceOps[+A, +CC[_], +C] extends Any { this: IterableOnce[A] =>
    *
    *  The matching prefix starts with the first element of this $coll,
    *  and the element following the prefix is the first element that
-   *  does not satisfy the predicate. The matching prefix may empty,
+   *  does not satisfy the predicate. The matching prefix may be empty,
    *  so that this method returns the entire $coll.
    *
    *  Example:
@@ -1188,7 +1188,20 @@ trait IterableOnceOps[+A, +CC[_], +C] extends Any { this: IterableOnce[A] =>
     None
   }
 
-  @deprecated("`aggregate` is not relevant for sequential collections. Use `foldLeft(z)(seqop)` instead.", "2.13.0")
+  /** Aggregates the results of applying an operator to subsequent elements.
+   *
+   *  Since this method degenerates to `foldLeft` for sequential (non-parallel) collections,
+   *  where the combining operation is ignored, it is advisable to prefer `foldLeft` for that case.
+   *
+   *  For [[https://github.com/scala/scala-parallel-collections parallel collections]],
+   *  use the `aggregate` method specified by `scala.collection.parallel.ParIterableLike`.
+   *
+   *  @param   z      the start value, a neutral element for `seqop`.
+   *  @param   seqop  the binary operator used to accumulate the result.
+   *  @param   combop an associative operator for combining sequential results, unused for sequential collections.
+   *  @tparam  B      the result type, produced by `seqop`, `combop`, and by this function as a final result.
+   */
+  @deprecated("For sequential collections, prefer `foldLeft(z)(seqop)`. For parallel collections, use `ParIterableLike#aggregate`.", "2.13.0")
   def aggregate[B](z: => B)(seqop: (B, A) => B, combop: (B, B) => B): B = foldLeft(z)(seqop)
 
   /** Tests whether every element of this collection's iterator relates to the

src/library/scala/collection/Map.scala

@@ -276,13 +276,14 @@ trait MapOps[K, +V, +CC[_, _] <: IterableOps[_, AnyConstr, _], +C]
   def mapValues[W](f: V => W): MapView[K, W] = new MapView.MapValues(this, f)
 
   /** Defines the default value computation for the map,
-    *  returned when a key is not found
-    *  The method implemented here throws an exception,
-    *  but it might be overridden in subclasses.
-    *
-    *  @param key the given key value for which a binding is missing.
-    *  @throws NoSuchElementException
-    */
+   *  returned when a key is not found.
+   *
+   *  The method implemented here throws an exception,
+   *  but it may be overridden by subclasses.
+   *
+   *  @param key the given key value for which a binding is missing.
+   *  @throws NoSuchElementException if no default value is defined
+   */
   @throws[NoSuchElementException]
   def default(key: K): V =
     throw new NoSuchElementException("key not found: " + key)

src/library/scala/collection/Seq.scala

@@ -928,7 +928,7 @@ trait SeqOps[+A, +CC[_], +C] extends Any
     *
     * Patching at negative indices is the same as patching starting at 0.
     * Patching at indices at or larger than the length of the original $coll appends the patch to the end.
-    * If more values are replaced than actually exist, the excess is ignored.
+    * If the `replaced` count would exceed the available elements, the difference in excess is ignored.
     *
     *  @param  from     the index of the first replaced element
     *  @param  other    the replacement sequence

src/library/scala/collection/StringOps.scala

@@ -973,36 +973,38 @@ final class StringOps(private val s: String) extends AnyVal {
   }
 
   /** Uses the underlying string as a pattern (in a fashion similar to
-    *  printf in C), and uses the supplied arguments to fill in the
-    *  holes.
-    *
-    *    The interpretation of the formatting patterns is described in
-    *    [[java.util.Formatter]], with the addition that
-    *    classes deriving from `ScalaNumber` (such as [[scala.BigInt]] and
-    *    [[scala.BigDecimal]]) are unwrapped to pass a type which `Formatter`
-    *    understands.
-    *
-    *  @param args the arguments used to instantiating the pattern.
-    *  @throws java.lang.IllegalArgumentException
-    */
-  def format(args : Any*): String =
-    java.lang.String.format(s, args map unwrapArg: _*)
+   *  printf in C), and uses the supplied arguments to fill in the
+   *  holes.
+   *
+   *  The interpretation of the formatting patterns is described in
+   *  [[java.util.Formatter]], with the addition that
+   *  classes deriving from `ScalaNumber` (such as [[scala.BigInt]] and
+   *  [[scala.BigDecimal]]) are unwrapped to pass a type which `Formatter` understands.
+   *
+   *  See [[scala.StringContext#f]] for a formatting interpolator that
+   *  checks the format string at compilation.
+   *
+   *  @param args the arguments used to instantiating the pattern.
+   *  @throws java.util.IllegalFormatException if the format contains syntax or conversion errors
+   */
+  def format(args: Any*): String =
+    java.lang.String.format(s, args.map(unwrapArg): _*)
 
   /** Like `format(args*)` but takes an initial `Locale` parameter
-    *  which influences formatting as in `java.lang.String`'s format.
-    *
-    *    The interpretation of the formatting patterns is described in
-    *    [[java.util.Formatter]], with the addition that
-    *    classes deriving from `ScalaNumber` (such as `scala.BigInt` and
-    *    `scala.BigDecimal`) are unwrapped to pass a type which `Formatter`
-    *    understands.
-    *
-    *  @param l    an instance of `java.util.Locale`
-    *  @param args the arguments used to instantiating the pattern.
-    *  @throws java.lang.IllegalArgumentException
-    */
+   *  which influences formatting as in `java.lang.String`'s format.
+   *
+   *    The interpretation of the formatting patterns is described in
+   *    [[java.util.Formatter]], with the addition that
+   *    classes deriving from `ScalaNumber` (such as `scala.BigInt` and
+   *    `scala.BigDecimal`) are unwrapped to pass a type which `Formatter`
+   *    understands.
+   *
+   *  @param l    an instance of `java.util.Locale`
+   *  @param args the arguments used to instantiating the pattern.
+   *  @throws java.util.IllegalFormatException if the format contains syntax or conversion errors
+   */
   def formatLocal(l: java.util.Locale, args: Any*): String =
-    java.lang.String.format(l, s, args map unwrapArg: _*)
+    java.lang.String.format(l, s, args.map(unwrapArg): _*)
 
   def compare(that: String): Int = s.compareTo(that)
 

src/library/scala/collection/immutable/Queue.scala

@@ -163,11 +163,11 @@ sealed class Queue[+A] protected(protected val in: List[A], protected val out: L
   def enqueueAll[B >: A](iter: scala.collection.Iterable[B]): Queue[B] = appendedAll(iter)
 
   /** Returns a tuple with the first element in the queue,
-    *  and a new queue with this element removed.
-    *
-    *  @throws NoSuchElementException
-    *  @return the first element of the queue.
-    */
+   *  and a new queue with this element removed.
+   *
+   *  @return the first element of the queue.
+   *  @throws NoSuchElementException if the queue is empty
+   */
   def dequeue: (A, Queue[A]) = out match {
     case Nil if !in.isEmpty => val rev = in.reverse ; (rev.head, new Queue(Nil, rev.tail))
     case x :: xs            => (x, new Queue(in, xs))
@@ -182,11 +182,11 @@ sealed class Queue[+A] protected(protected val in: List[A], protected val out: L
   def dequeueOption: Option[(A, Queue[A])] = if(isEmpty) None else Some(dequeue)
 
   /** Returns the first element in the queue, or throws an error if there
-    *  is no element contained in the queue.
-    *
-    *  @throws NoSuchElementException
-    *  @return the first element.
-    */
+   *  is no element contained in the queue.
+   *
+   *  @throws NoSuchElementException if the queue is empty
+   *  @return the first element.
+   */
   def front: A = head
 
   /** Returns a string representation of this queue.

src/library/scala/collection/mutable/AnyRefMap.scala

@@ -475,11 +475,30 @@ class AnyRefMap[K <: AnyRef, V] private[collection] (defaultEntry: K => V, initi
     this
   }
 
-  // The implicit dummy parameter is necessary to distinguish these methods from the base methods they overload (not override)
+  // The implicit dummy parameter is necessary to distinguish these methods from the base methods they overload (not override).
+  // Previously, in Scala 2, f took `K with AnyRef` scala/bug#11035
+  /**
+   * An overload of `map` which produces an `AnyRefMap`.
+   *
+   * @param f the mapping function must produce a key-value pair where the key is an `AnyRef`
+   * @param dummy an implicit placeholder for purposes of distinguishing the (erased) signature of this method
+   */
   def map[K2 <: AnyRef, V2](f: ((K, V)) => (K2, V2))(implicit dummy: DummyImplicit): AnyRefMap[K2, V2] =
     AnyRefMap.from(new View.Map(this, f))
+  /**
+   * An overload of `flatMap` which produces an `AnyRefMap`.
+   *
+   * @param f the mapping function must produce key-value pairs where the key is an `AnyRef`
+   * @param dummy an implicit placeholder for purposes of distinguishing the (erased) signature of this method
+   */
   def flatMap[K2 <: AnyRef, V2](f: ((K, V)) => IterableOnce[(K2, V2)])(implicit dummy: DummyImplicit): AnyRefMap[K2, V2] =
     AnyRefMap.from(new View.FlatMap(this, f))
+  /**
+   * An overload of `collect` which produces an `AnyRefMap`.
+   *
+   * @param pf the mapping function must produce a key-value pair where the key is an `AnyRef`
+   * @param dummy an implicit placeholder for purposes of distinguishing the (erased) signature of this method
+   */
   def collect[K2 <: AnyRef, V2](pf: PartialFunction[(K, V), (K2, V2)])(implicit dummy: DummyImplicit): AnyRefMap[K2, V2] =
     strictOptimizedCollect(AnyRefMap.newBuilder[K2, V2], pf)
 

src/library/scala/collection/mutable/ArrayBuffer.scala

@@ -77,6 +77,10 @@ class ArrayBuffer[A] private (initialElements: Array[AnyRef], initialSize: Int)
     array = ArrayBuffer.ensureSize(array, size0, size0.toLong + n)
   }
 
+  /** Uses the given size to resize internal storage, if necessary.
+   *
+   *  @param size Expected maximum number of elements.
+   */
   def sizeHint(size: Int): Unit =
     if(size > length && size >= 1) ensureSize(size)
 

src/library/scala/collection/mutable/ArrayBuilder.scala

@@ -27,8 +27,10 @@ sealed abstract class ArrayBuilder[T]
   protected[this] def elems: Array[T]
   protected var size: Int = 0
 
+  /** Current number of elements. */
   def length: Int = size
 
+  /** Current number of elements. */
   override def knownSize: Int = size
 
   protected[this] final def ensureSize(size: Int): Unit = {

src/library/scala/collection/mutable/Buffer.scala

@@ -37,23 +37,28 @@ trait Buffer[A]
   def prepend(elem: A): this.type
 
   /** Appends the given elements to this buffer.
-    *
-    *  @param elem  the element to append.
-    */
+   *
+   *  @param elem the element to append.
+   *  @return     this $coll
+   */
   @`inline` final def append(elem: A): this.type = addOne(elem)
 
   @deprecated("Use appendAll instead", "2.13.0")
   @`inline` final def append(elems: A*): this.type = addAll(elems)
 
   /** Appends the elements contained in a iterable object to this buffer.
-    *  @param xs  the iterable object containing the elements to append.
-    */
-  @`inline` final def appendAll(xs: IterableOnce[A]): this.type = addAll(xs)
-
+   *  @param elems  the iterable object containing the elements to append.
+   *  @return       this $coll
+   */
+  @`inline` final def appendAll(@deprecatedName("xs") elems: IterableOnce[A]): this.type = addAll(elems)
 
   /** Alias for `prepend` */
   @`inline` final def +=: (elem: A): this.type = prepend(elem)
 
+  /** Prepends the elements contained in a iterable object to this buffer.
+   *  @param elems  the iterable object containing the elements to append.
+   *  @return       this $coll
+   */
   def prependAll(elems: IterableOnce[A]): this.type = { insertAll(0, elems); this }
 
   @deprecated("Use prependAll instead", "2.13.0")
@@ -132,6 +137,17 @@ trait Buffer[A]
   @deprecated("use dropRightInPlace instead", since = "2.13.4")
   def trimEnd(n: Int): Unit = dropRightInPlace(n)
 
+  /** Replaces a slice of elements in this $coll by another sequence of elements.
+   *
+   *  Patching at negative indices is the same as patching starting at 0.
+   *  Patching at indices at or larger than the length of the original $coll appends the patch to the end.
+   *  If the `replaced` count would exceed the available elements, the difference in excess is ignored.
+   *
+   *  @param  from     the index of the first replaced element
+   *  @param  patch    the replacement sequence
+   *  @param  replaced the number of elements to drop in the original $coll
+   *  @return          this $coll
+   */
   def patchInPlace(from: Int, patch: scala.collection.IterableOnce[A], replaced: Int): this.type
 
   // +=, ++=, clear inherited from Growable
@@ -141,29 +157,85 @@ trait Buffer[A]
   // def +=:(elem1: A, elem2: A, elems: A*): this.type = elem1 +=: elem2 +=: elems ++=: this
   // def ++=:(elems: IterableOnce[A]): this.type = { insertAll(0, elems); this }
 
+  /** Removes the first `n` elements from this $coll.
+   *
+   *  @param  n the number of elements to remove
+   *  @return this $coll
+   *
+   */
   def dropInPlace(n: Int): this.type = { remove(0, normalized(n)); this }
+
+  /** Removes the last `n` elements from this $coll.
+   *
+   *  @param  n the number of elements to remove
+   *  @return this $coll
+   *
+   */
   def dropRightInPlace(n: Int): this.type = {
     val norm = normalized(n)
     remove(length - norm, norm)
     this
   }
+
+  /** Retains the first `n` elements from this $coll and removes the rest.
+   *
+   *  @param  n the number of elements to retain
+   *  @return this $coll
+   *
+   */
   def takeInPlace(n: Int): this.type = {
     val norm = normalized(n)
     remove(norm, length - norm)
     this
   }
+
+  /** Retains the last `n` elements from this $coll and removes the rest.
+   *
+   *  @param  n the number of elements to retain
+   *  @return this $coll
+   *
+   */
   def takeRightInPlace(n: Int): this.type = { remove(0, length - normalized(n)); this }
+
+  /** Retains the specified slice from this $coll and removes the rest.
+   *
+   *  @param  start the lowest index to include
+   *  @param  end   the lowest index to exclude
+   *  @return this $coll
+   *
+   */
   def sliceInPlace(start: Int, end: Int): this.type = takeInPlace(end).dropInPlace(start)
+
   private def normalized(n: Int): Int = math.min(math.max(n, 0), length)
 
+  /** Drops the longest prefix of elements that satisfy a predicate.
+   *
+   *  @param   p  The predicate used to test elements.
+   *  @return this $coll
+   *  @see [[dropWhile]]
+   */
   def dropWhileInPlace(p: A => Boolean): this.type = {
     val idx = indexWhere(!p(_))
     if (idx < 0) { clear(); this } else dropInPlace(idx)
   }
+
+  /** Retains the longest prefix of elements that satisfy a predicate.
+   *
+   *  @param   p  The predicate used to test elements.
+   *  @return this $coll
+   *  @see [[takeWhile]]
+   */
   def takeWhileInPlace(p: A => Boolean): this.type = {
     val idx = indexWhere(!p(_))
     if (idx < 0) this else takeInPlace(idx)
   }
+
+  /** Append the given element to this $coll until a target length is reached.
+   *
+   *  @param   len   the target length
+   *  @param   elem  the padding value
+   *  @return this $coll
+   */
   def padToInPlace(len: Int, elem: A): this.type = {
     while (length < len) +=(elem)
     this
@@ -180,6 +252,11 @@ trait IndexedBuffer[A] extends IndexedSeq[A]
 
   override def iterableFactory: SeqFactory[IndexedBuffer] = IndexedBuffer
 
+  /** Replace the contents of this $coll with the flatmapped result.
+   *
+   *  @param f the mapping function
+   *  @return this $coll
+   */
   def flatMapInPlace(f: A => IterableOnce[A]): this.type = {
     // There's scope for a better implementation which copies elements in place.
     var i = 0
@@ -192,6 +269,11 @@ trait IndexedBuffer[A] extends IndexedSeq[A]
     this
   }
 
+  /** Replace the contents of this $coll with the filtered result.
+   *
+   *  @param f the filtering function
+   *  @return this $coll
+   */
   def filterInPlace(p: A => Boolean): this.type = {
     var i, j = 0
     while (i < size) {