Make style-only changes to doc comments for the standard library.

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.

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