Make style-only changes to doc comments for the standard library. (#24754)

The following style changes are made in this commit:

1. Use indicative mood (Returns, Builds, ... not imperative mood
(Return, Build, ...).
2. Terminate initial sentence with a period.
3. Place code artifact names (for classes, methods, etc.) in backticks
so they will render in code font.

Only doc comments are changed, and only to make the above style changes.

Reasoning: Indicative mood is recommended over imperative mood by the
Scaladoc Style Guide:

https://docs.scala-lang.org/style/scaladoc.html

Which says: Document what the method does do not what the method should
do. In other words, say “returns the result of applying f to x” rather
than “return the result of applying f to x”. Subtle, but important.

It is also what maybe 60% of Scaladoc comments in the standard library
does, so this PR makes that consistent. It is also the way doc comments
are written in Javadoc for the Java standard library. It is essentially
writing the docoumentation as if you are explaining to a user (Returns
something...) rather than an implementor (Return something...).

The terminating period is also used some of the time, but not always, in
the existing doc comments for the standard library> This makes it
consistent. Some phrases are not full sentences, but you can think of
the subject as "implicit." "Returns true" means "This method returns
true." Also if you have a bullet list where some of the items are
complete sentences, and others not, the style guide (Chicago Manual of
Style) I go by suggests putting periods after all items. And the Java
standard library documentation seems to do this.

A few spots are missed in this PR, which I jotted down as I reviewed
*every* changed file. But it hits most of them, so I'm hoping we can
merge this into main and I can do further cleanup in later PRs.

Author: bvenners

library-js/src/scala/Array.scala

@@ -61,7 +61,7 @@ object Array {
     val emptyObjectArray  = new Array[Object](0)
   }
 
-  /** Provides an implicit conversion from the Array object to a collection Factory */
+  /** Provides an implicit conversion from the Array object to a collection Factory. */
   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 {
@@ -109,7 +109,7 @@ object Array {
     }
   }
 
-  /** Copy one array to another.
+  /** Copies one array to another.
    *  Equivalent to Java's
    *    `System.arraycopy(src, srcPos, dest, destPos, length)`,
    *  except that this also works for polymorphic and boxed arrays.
@@ -132,7 +132,7 @@ object Array {
       slowcopy(src, srcPos, dest, destPos, length)
   }
 
-  /** Copy one array to another, truncating or padding with default values (if
+  /** Copies one array to another, truncating or padding with default values (if
     * necessary) so the copy has the specified length.
     *
     * Equivalent to Java's
@@ -154,7 +154,7 @@ object Array {
     case x: Array[Boolean]    => java.util.Arrays.copyOf(x, newLength)
   }).asInstanceOf[Array[A]]
 
-  /** Copy one array to another, truncating or padding with default values (if
+  /** Copies one array to another, truncating or padding with default values (if
     * necessary) so the copy has the specified length. The new array can have
     * a different type than the original one as long as the values are
     * assignment-compatible. When copying between primitive and object arrays,
@@ -192,7 +192,7 @@ object Array {
     result
   }
 
-  /** Returns an array of length 0 */
+  /** Returns an array of length 0. */
   def empty[T: ClassTag]: Array[T] = new Array[T](0)
 
   /** Creates an array with given elements.
@@ -212,7 +212,7 @@ object Array {
     array
   }
 
-  /** Creates an array of `Boolean` objects */
+  /** Creates an array of `Boolean` objects. */
   // Subject to a compiler optimization in Cleanup, see above.
   def apply(x: Boolean, xs: Boolean*): Array[Boolean] = {
     val array = new Array[Boolean](xs.length + 1)
@@ -225,7 +225,7 @@ object Array {
     array
   }
 
-  /** Creates an array of `Byte` objects */
+  /** Creates an array of `Byte` objects. */
   // Subject to a compiler optimization in Cleanup, see above.
   def apply(x: Byte, xs: Byte*): Array[Byte] = {
     val array = new Array[Byte](xs.length + 1)
@@ -238,7 +238,7 @@ object Array {
     array
   }
 
-  /** Creates an array of `Short` objects */
+  /** Creates an array of `Short` objects. */
   // Subject to a compiler optimization in Cleanup, see above.
   def apply(x: Short, xs: Short*): Array[Short] = {
     val array = new Array[Short](xs.length + 1)
@@ -251,7 +251,7 @@ object Array {
     array
   }
 
-  /** Creates an array of `Char` objects */
+  /** Creates an array of `Char` objects. */
   // Subject to a compiler optimization in Cleanup, see above.
   def apply(x: Char, xs: Char*): Array[Char] = {
     val array = new Array[Char](xs.length + 1)
@@ -264,7 +264,7 @@ object Array {
     array
   }
 
-  /** Creates an array of `Int` objects */
+  /** Creates an array of `Int` objects. */
   // Subject to a compiler optimization in Cleanup, see above.
   def apply(x: Int, xs: Int*): Array[Int] = {
     val array = new Array[Int](xs.length + 1)
@@ -277,7 +277,7 @@ object Array {
     array
   }
 
-  /** Creates an array of `Long` objects */
+  /** Creates an array of `Long` objects. */
   // Subject to a compiler optimization in Cleanup, see above.
   def apply(x: Long, xs: Long*): Array[Long] = {
     val array = new Array[Long](xs.length + 1)
@@ -290,7 +290,7 @@ object Array {
     array
   }
 
-  /** Creates an array of `Float` objects */
+  /** Creates an array of `Float` objects. */
   // Subject to a compiler optimization in Cleanup, see above.
   def apply(x: Float, xs: Float*): Array[Float] = {
     val array = new Array[Float](xs.length + 1)
@@ -303,7 +303,7 @@ object Array {
     array
   }
 
-  /** Creates an array of `Double` objects */
+  /** Creates an array of `Double` objects. */
   // Subject to a compiler optimization in Cleanup, see above.
   def apply(x: Double, xs: Double*): Array[Double] = {
     val array = new Array[Double](xs.length + 1)
@@ -316,7 +316,7 @@ object Array {
     array
   }
 
-  /** Creates an array of `Unit` objects */
+  /** Creates an array of `Unit` objects. */
   def apply(x: Unit, xs: Unit*): Array[Unit] = {
     val array = new Array[Unit](xs.length + 1)
     array(0) = x
@@ -328,23 +328,23 @@ object Array {
     array
   }
 
-  /** Creates array with given dimensions */
+  /** Creates array with given dimensions. */
   def ofDim[T: ClassTag](n1: Int): Array[T] =
     new Array[T](n1)
-  /** Creates a 2-dimensional array */
+  /** Creates a 2-dimensional array. */
   def ofDim[T: ClassTag](n1: Int, n2: Int): Array[Array[T]] = {
     val arr: Array[Array[T]] = (new Array[Array[T]](n1): Array[Array[T]])
     for (i <- 0 until n1) arr(i) = new Array[T](n2)
     arr
     // tabulate(n1)(_ => ofDim[T](n2))
   }
-  /** Creates a 3-dimensional array */
+  /** Creates a 3-dimensional array. */
   def ofDim[T: ClassTag](n1: Int, n2: Int, n3: Int): Array[Array[Array[T]]] =
     tabulate(n1)(_ => ofDim[T](n2, n3))
-  /** Creates a 4-dimensional array */
+  /** Creates a 4-dimensional array. */
   def ofDim[T: ClassTag](n1: Int, n2: Int, n3: Int, n4: Int): Array[Array[Array[Array[T]]]] =
     tabulate(n1)(_ => ofDim[T](n2, n3, n4))
-  /** Creates a 5-dimensional array */
+  /** Creates a 5-dimensional array. */
   def ofDim[T: ClassTag](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int): Array[Array[Array[Array[Array[T]]]]] =
     tabulate(n1)(_ => ofDim[T](n2, n3, n4, n5))
 
@@ -662,7 +662,7 @@ object Array {
  */
 final class Array[T](_length: Int) extends java.io.Serializable with java.lang.Cloneable { self =>
 
-  /** The length of the array */
+  /** The length of the array. */
   def length: Int = throw new Error()
 
   /** The element at given index.
@@ -676,7 +676,7 @@ final class Array[T](_length: Int) extends java.io.Serializable with java.lang.C
    */
   def apply(i: Int): T = throw new Error()
 
-  /** Update the element at given index.
+  /** Updates the element at given index.
    *
    *  Indices start at `0`; `xs.update(i, x)` replaces the i^th^ element in the array.
    *  Note the syntax `xs(i) = x` is a shorthand for `xs.update(i, x)`.
@@ -687,7 +687,7 @@ final class Array[T](_length: Int) extends java.io.Serializable with java.lang.C
    */
   def update(i: Int, x: T): Unit = { throw new Error() }
 
-  /** Clone the Array.
+  /** Clones the Array.
    *
    *  @return A clone of the Array.
    */

library-js/src/scala/Console.scala

@@ -138,15 +138,15 @@ object Console extends AnsiColor {
   protected def setErrDirect(err: PrintStream): Unit  = errVar.value = err
   protected def setInDirect(in: BufferedReader): Unit = inVar.value = in
 
-  /** The default output, can be overridden by `withOut`
+  /** The default output, can be overridden by `withOut`.
    *  @group io-default
    */
   def out = outVar.value
-  /** The default error, can be overridden by `withErr`
+  /** The default error, can be overridden by `withErr`.
    *  @group io-default
    */
   def err = errVar.value
-  /** The default input, can be overridden by `withIn`
+  /** The default input, can be overridden by `withIn`.
    *  @group io-default
    */
   def in = inVar.value
@@ -181,7 +181,7 @@ object Console extends AnsiColor {
   def withOut[T](out: OutputStream)(thunk: =>T): T =
     withOut(new PrintStream(out))(thunk)
 
-  /** Set the default error stream for the duration
+  /** Sets the default error stream for the duration
    *  of execution of one thunk.
    *  @example {{{
    *  withErr(Console.out) { err.println("This goes to default _out_") }

library-js/src/scala/Enumeration.scala

@@ -149,7 +149,7 @@ abstract class Enumeration (initial: Int) extends Serializable {
    */
   final def apply(x: Int): Value = vmap(x)
 
-  /** Return a `Value` from this `Enumeration` whose name matches
+  /** Returns a `Value` from this `Enumeration` whose name matches
    *  the argument `s`.  The names are determined automatically via reflection.
    *
    * @param  s an `Enumeration` name
@@ -207,9 +207,9 @@ abstract class Enumeration (initial: Int) extends Serializable {
   /** The type of the enumerated values. */
   @SerialVersionUID(7091335633555234129L)
   abstract class Value extends Ordered[Value] with Serializable {
-    /** the id and bit location of this enumeration value */
+    /** The id and bit location of this enumeration value. */
     def id: Int
-    /** a marker so we can tell whose values belong to whom come reflective-naming time */
+    /** A marker so we can tell whose values belong to whom come reflective-naming time. */
     private[Enumeration] val outerEnum = thisenum
 
     override def compare(that: Value): Int =
@@ -222,7 +222,7 @@ abstract class Enumeration (initial: Int) extends Serializable {
     }
     override def hashCode: Int = id.##
 
-    /** Create a ValueSet which contains this value and another one */
+    /** Creates a ValueSet which contains this value and another one. */
     def + (v: Value) = ValueSet(this, v)
   }
 
@@ -255,7 +255,7 @@ abstract class Enumeration (initial: Int) extends Serializable {
     }
   }
 
-  /** An ordering by id for values of this set */
+  /** An ordering by id for values of this set. */
   implicit object ValueOrdering extends Ordering[Value] {
     def compare(x: Value, y: Value): Int = x compare y
   }
@@ -308,18 +308,18 @@ abstract class Enumeration (initial: Int) extends Serializable {
       super[SortedSet].collect[B](pf)
   }
 
-  /** A factory object for value sets */
+  /** A factory object for value sets. */
   @SerialVersionUID(3L)
   object ValueSet extends SpecificIterableFactory[Value, ValueSet] {
     private final val ordMsg = "No implicit Ordering[${B}] found to build a SortedSet[${B}]. You may want to upcast to a Set[Value] first by calling `unsorted`."
     private final val zipOrdMsg = "No implicit Ordering[${B}] found to build a SortedSet[(Value, ${B})]. You may want to upcast to a Set[Value] first by calling `unsorted`."
 
-    /** The empty value set */
+    /** The empty value set. */
     val empty = new ValueSet(immutable.BitSet.empty)
     /** A value set containing all the values for the zero-adjusted ids
-     *  corresponding to the bits in an array */
+     *  corresponding to the bits in an array. */
     def fromBitMask(elems: Array[Long]): ValueSet = new ValueSet(immutable.BitSet.fromBitMask(elems))
-    /** A builder object for value sets */
+    /** A builder object for value sets. */
     def newBuilder: mutable.Builder[Value, ValueSet] = new mutable.Builder[Value, ValueSet] {
       private[this] val b = new mutable.BitSet
       def addOne (x: Value) = { b += (x.id - bottomId); this }

library-js/src/scala/collection/immutable/NumericRange.scala

@@ -93,13 +93,13 @@ sealed class NumericRange[T](
     else if(isInclusive) new NumericRange.Inclusive(start + step, end, step)
     else new NumericRange.Exclusive(start + step, end, step)
 
-  /** Create a new range with the start and end values of this range and
+  /** Creates a new range with the start and end values of this range and
     *  a new `step`.
     */
   def by(newStep: T): NumericRange[T] = copy(start, end, newStep)
 
 
-  /** Create a copy of this range.
+  /** Creates a copy of this range.
     */
   def copy(start: T, end: T, step: T): NumericRange[T] =
     new NumericRange(start, end, step, isInclusive)

library-js/src/scala/collection/immutable/Range.scala

@@ -157,7 +157,7 @@ sealed abstract class Range(
   final protected def copy(start: Int = start, end: Int = end, step: Int = step, isInclusive: Boolean = isInclusive): Range =
     if(isInclusive) new Range.Inclusive(start, end, step) else new Range.Exclusive(start, end, step)
 
-  /** Create a new range with the `start` and `end` values of this range and
+  /** Creates a new range with the `start` and `end` values of this range and
     *  a new `step`.
     *
     *  @return a new range with a different step
@@ -364,7 +364,7 @@ sealed abstract class Range(
     if (isEmpty) this
     else new Range.Inclusive(last, start, -step)
 
-  /** Make range inclusive.
+  /** Makes range inclusive.
     */
   final def inclusive: Range =
     if (isInclusive) this
@@ -566,21 +566,21 @@ object Range {
   def count(start: Int, end: Int, step: Int): Int =
     count(start, end, step, isInclusive = false)
 
-  /** Make a range from `start` until `end` (exclusive) with given step value.
+  /** Makes a range from `start` until `end` (exclusive) with given step value.
     * @note step != 0
     */
   def apply(start: Int, end: Int, step: Int): Range.Exclusive = new Range.Exclusive(start, end, step)
 
-  /** Make a range from `start` until `end` (exclusive) with step value 1.
+  /** Makes a range from `start` until `end` (exclusive) with step value 1.
     */
   def apply(start: Int, end: Int): Range.Exclusive = new Range.Exclusive(start, end, 1)
 
-  /** Make an inclusive range from `start` to `end` with given step value.
+  /** Makes an inclusive range from `start` to `end` with given step value.
     * @note step != 0
     */
   def inclusive(start: Int, end: Int, step: Int): Range.Inclusive = new Range.Inclusive(start, end, step)
 
-  /** Make an inclusive range from `start` to `end` with step value 1.
+  /** Makes an inclusive range from `start` to `end` with step value 1.
     */
   def inclusive(start: Int, end: Int): Range.Inclusive = new Range.Inclusive(start, end, 1)
 

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

@@ -54,10 +54,10 @@ sealed abstract class ArrayBuilder[T]
 
   protected[this] def resize(size: Int): Unit
 
-  /** Add all elements of an array */
+  /** Adds all elements of an array. */
   def addAll(xs: Array[_ <: T]): this.type = addAll(xs, 0, xs.length)
 
-  /** Add a slice of an array */
+  /** Adds a slice of an array. */
   def addAll(xs: Array[_ <: T], offset: Int, length: Int): this.type = {
     ensureSize(this.size + length)
     Array.copy(xs, offset, elems.nn, this.size, length)
@@ -146,7 +146,7 @@ object ArrayBuilder {
       this
     }
 
-    /** Add a slice of an array */
+    /** Adds a slice of an array. */
     override def addAll(xs: Array[_ <: T], offset: Int, length: Int): this.type = {
       val end = offset + length
       var i = offset

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

@@ -52,15 +52,15 @@ trait Buffer[A]
   @`inline` final def appendAll(xs: IterableOnce[A]): this.type = addAll(xs)
 
 
-  /** Alias for `prepend` */
+  /** Alias for `prepend`. */
   @`inline` final def +=: (elem: A): this.type = prepend(elem)
 
   def prependAll(elems: IterableOnce[A]): this.type = { insertAll(0, elems); this }
 
   @deprecated("Use prependAll instead", "2.13.0")
   @`inline` final def prepend(elems: A*): this.type = prependAll(elems)
 
-  /** Alias for `prependAll` */
+  /** Alias for `prependAll`. */
   @inline final def ++=:(elems: IterableOnce[A]): this.type = prependAll(elems)
 
   /** Inserts a new element at a given index into this buffer.

library-js/src/scala/reflect/ClassTag.scala

@@ -61,10 +61,10 @@ trait ClassTag[T] extends ClassManifestDeprecatedApis[T] with Equals with Serial
    */
   def runtimeClass: jClass[_]
 
-  /** Produces a `ClassTag` that knows how to instantiate an `Array[Array[T]]` */
+  /** Produces a `ClassTag` that knows how to instantiate an `Array[Array[T]]`. */
   def wrap: ClassTag[Array[T]] = ClassTag[Array[T]](arrayClass(runtimeClass))
 
-  /** Produces a new array with element type `T` and length `len` */
+  /** Produces a new array with element type `T` and length `len`. */
   def newArray(len: Int): Array[T] =
     java.lang.reflect.Array.newInstance(runtimeClass, len).asInstanceOf[Array[T]]