Scaladoc: convert remaining wikidoc syntax in stdlib comments to markdown

library/resources/rootdoc.md

@@ -0,0 +1,47 @@
+This is the documentation for the Scala standard library.
+
+## Package structure
+
+The [[scala]] package contains core types like [[scala.Int Int]], [[scala.Float Float]], [[scala.Array Array]]
+or [[scala.Option Option]] which are accessible in all Scala compilation units without explicit qualification or
+imports.
+
+Notable packages include:
+
+  - [[scala.collection]]    and its sub-packages contain Scala's collections framework
+    - [[scala.collection.immutable]] - Immutable, sequential data-structures such as
+      [[scala.collection.immutable.Vector Vector]], [[scala.collection.immutable.List List]],
+      [[scala.collection.immutable.Range Range]], [[scala.collection.immutable.HashMap HashMap]] or
+      [[scala.collection.immutable.HashSet HashSet]]
+    - [[scala.collection.mutable]] - Mutable, sequential data-structures such as
+      [[scala.collection.mutable.ArrayBuffer ArrayBuffer]],
+      [[scala.collection.mutable.StringBuilder StringBuilder]],
+      [[scala.collection.mutable.HashMap HashMap]] or [[scala.collection.mutable.HashSet HashSet]]
+    - [[scala.collection.concurrent]] - Mutable, concurrent data-structures such as
+      [[scala.collection.concurrent.TrieMap TrieMap]]
+  - [[scala.concurrent]]    - Primitives for concurrent programming such as
+    [[scala.concurrent.Future Futures]] and [[scala.concurrent.Promise Promises]]
+  - [[scala.io]]            - Input and output operations
+  - [[scala.math]]          - Basic math functions and additional numeric types like
+    [[scala.math.BigInt BigInt]] and [[scala.math.BigDecimal BigDecimal]]
+  - [[scala.sys]]           - Interaction with other processes and the operating system
+  - [[scala.util.matching]] - [[scala.util.matching.Regex Regular expressions]]
+
+Other packages exist.  See the complete list on the right.
+
+Additional parts of the standard library are shipped as separate libraries. These include:
+
+  - [[https://www.scala-lang.org/api/2.13.x/scala-reflect/scala/reflect/index.html scala.reflect]] - Scala's reflection API (scala-reflect.jar)
+  - [[https://github.com/scala/scala-xml scala.xml]] - XML parsing, manipulation, and serialization (scala-xml.jar)
+  - [[https://github.com/scala/scala-parallel-collections scala.collection.parallel]] - Parallel collections (scala-parallel-collections.jar)
+  - [[https://github.com/scala/scala-parser-combinators scala.util.parsing]] - Parser combinators (scala-parser-combinators.jar)
+  - [[https://github.com/scala/scala-swing scala.swing]] - A convenient wrapper around Java's GUI framework called Swing (scala-swing.jar)
+
+## Automatic imports
+
+Identifiers in the scala package and the [[scala.Predef]] object are always in scope by default.
+
+Some of these identifiers are type aliases provided as shortcuts to commonly used classes.  For example, `List` is an alias for
+[[scala.collection.immutable.List]].
+
+Other aliases refer to classes provided by the underlying platform.  For example, on the JVM, `String` is an alias for `java.lang.String`.

library/src/scala/Array.scala

@@ -804,7 +804,7 @@ final class Array[T](_length: Int) extends java.io.Serializable with java.lang.C
 
   /** Updates the element at given index.
    *
-   *  Indices start at `0`; `xs.update(i, x)` replaces the i^th^ element in the array.
+   *  Indices start at `0`; `xs.update(i, x)` replaces the i<sup>th</sup> element in the array.
    *  Note the syntax `xs(i) = x` is a shorthand for `xs.update(i, x)`.
    *
    *  @param    i   the index

library/src/scala/Byte.scala

@@ -651,8 +651,8 @@ object Byte extends AnyValCompanion {
   implicit def byte2double(x: Byte): Double = x.toDouble
 
   extension (self: Byte) {
-    /** Returns `'''true'''` if this number has no decimal component.
-      * Always `'''true'''` for `Byte`.
+    /** Returns `true` if this number has no decimal component.
+      * Always `true` for `Byte`.
       */
     @deprecated("isWhole on Byte is always true", "2.12.15")
     def isWhole: Boolean = true

library/src/scala/Char.scala

@@ -653,8 +653,8 @@ object Char extends AnyValCompanion {
 
   extension (self: Char) {
 
-    /** Returns `'''true'''` if this number has no decimal component.
-      * Always `'''true'''` for `RichInt`.
+    /** Returns `true` if this number has no decimal component.
+      * Always `true` for `RichInt`.
       */
     @deprecated("isWhole on Char is always true", "2.12.15")
     def isWhole: Boolean = true

library/src/scala/Double.scala

@@ -395,7 +395,7 @@ object Double extends AnyValCompanion {
   override def toString() = "object scala.Double"
 
   extension (self: Double) {
-    /** Returns `'''true'''` if this number is finite and has no decimal component. */
+    /** Returns `true` if this number is finite and has no decimal component. */
     def isWhole: Boolean = {
       val l = self.toLong
       l.toDouble == self || l == Long.MaxValue && self < Double.PositiveInfinity || l == Long.MinValue && self > Double.NegativeInfinity

library/src/scala/Float.scala

@@ -402,7 +402,7 @@ object Float extends AnyValCompanion {
   implicit def float2double(x: Float): Double = x.toDouble
 
   extension (self: Float) {
-    /** Returns `'''true'''` if this number is finite and has no decimal component. */
+    /** Returns `true` if this number is finite and has no decimal component. */
     def isWhole: Boolean = {
       val i = self.toInt
       i.toFloat == self || i == Int.MaxValue && self < Float.PositiveInfinity || i == Int.MinValue && self > Float.NegativeInfinity

library/src/scala/Function.scala

@@ -16,8 +16,8 @@ import scala.language.`2.13`
 
 /** A module defining utility methods for higher-order functional programming. */
 object Function {
-  /** Given a sequence of functions `f,,1,,`, ..., `f,,n,,`, return the
-   *  function `f,,1,, andThen ... andThen f,,n,,`.
+  /** Given a sequence of functions <code>f<sub>1</sub></code>, ..., <code>f<sub>n</sub></code>, return the
+   *  function <code>f<sub>1</sub> andThen ... andThen f<sub>n</sub></code>.
    *
    *  @tparam T the common input and output type of the functions in the chain
    *  @param fs the given sequence of functions

library/src/scala/Int.scala

@@ -646,8 +646,8 @@ object Int extends AnyValCompanion {
   implicit def int2double(x: Int): Double = x.toDouble
 
   extension (self: Int) {
-    /** Returns `'''true'''` if this number has no decimal component.
-      * Always `'''true'''` for `Int`.
+    /** Returns `true` if this number has no decimal component.
+      * Always `true` for `Int`.
       */
     @deprecated("isWhole on Int is always true", "2.12.15")
     def isWhole: Boolean = true

library/src/scala/Long.scala

@@ -651,8 +651,8 @@ object Long extends AnyValCompanion {
   implicit def long2double(x: Long): Double = x.toDouble
 
   extension (self: Long) {
-    /** Returns `'''true'''` if this number has no decimal component.
-      * Always `'''true'''` for `Long`.
+    /** Returns `true` if this number has no decimal component.
+      * Always `true` for `Long`.
       */
     @deprecated("isWhole on Long is always true", "2.12.15")
     def isWhole: Boolean = true

library/src/scala/PartialFunction.scala

@@ -139,7 +139,7 @@ trait PartialFunction[-A, +B] extends Function1[A, B] { self: PartialFunction[A,
   /** Checks if a value is contained in the function's domain.
    *
    *  @param  x   the value to test
-   *  @return `**true**`, iff `x` is in the domain of this function, `**false**` otherwise.
+   *  @return `true`, iff `x` is in the domain of this function, `false` otherwise.
    */
   def isDefinedAt(x: A): Boolean
 

library/src/scala/Product.scala

@@ -22,12 +22,12 @@ import language.experimental.captureChecking
  */
 transparent trait Product extends Any with Equals {
   /** The size of this product.
-    *  @return     for a product `A(x,,1,,, ..., x,,k,,)`, returns `k`
+    *  @return     for a product <code>A(x<sub>1</sub>, ..., x<sub>k</sub>)</code>, returns `k`
     */
   def productArity: Int
 
-  /** The n^th^ element of this product, 0-based.  In other words, for a
-   *  product `A(x,,1,,, ..., x,,k,,)`, returns `x,,(n+1),,` where `0 <= n < k`.
+  /** The n<sup>th</sup> element of this product, 0-based.  In other words, for a
+   *  product <code>A(x<sub>1</sub>, ..., x<sub>k</sub>)</code>, returns <code>x<sub>(n+1)</sub></code> where `0 <= n < k`.
    *
    *  @param    n   the index of the element to return
    *  @throws       IndexOutOfBoundsException if the `n` is out of range(n < 0 || n >= productArity).
@@ -53,7 +53,7 @@ transparent trait Product extends Any with Equals {
    */
   def productPrefix: String = ""
 
-  /** The name of the n^th^ element of this product, 0-based.
+  /** The name of the n<sup>th</sup> element of this product, 0-based.
    *  In the default implementation, an empty string.
    *
    *  @param    n   the index of the element name to return

library/src/scala/Short.scala

@@ -650,8 +650,8 @@ object Short extends AnyValCompanion {
   implicit def short2double(x: Short): Double = x.toDouble
 
   extension (self: Short) {
-    /** Returns `'''true'''` if this number has no decimal component.
-      * Always `'''true'''` for `Short`.
+    /** Returns `true` if this number has no decimal component.
+      * Always `true` for `Short`.
       */
     @deprecated("isWhole on Short is always true", "2.12.15")
     def isWhole: Boolean = true

library/src/scala/collection/ArrayOps.scala

@@ -296,7 +296,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal {
   /** Method mirroring [[SeqOps.sizeIs]] for consistency, except it returns an `Int`
    *  because `size` is known and comparison is constant-time.
    *
-   *  These operations are equivalent to [[sizeCompare(Int) `sizeCompare(Int)`]], and
+   *  These operations are equivalent to [[sizeCompare(Int) sizeCompare(Int)]], and
    *  allow the following more readable usages:
    *
    *  ```
@@ -315,7 +315,7 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal {
   /** Method mirroring [[SeqOps.lengthIs]] for consistency, except it returns an `Int`
    *  because `length` is known and comparison is constant-time.
    *
-   *  These operations are equivalent to [[lengthCompare(Int) `lengthCompare(Int)`]], and
+   *  These operations are equivalent to [[lengthCompare(Int) lengthCompare(Int)]], and
    *  allow the following more readable usages:
    *
    *  ```
@@ -809,8 +809,8 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal {
    *  all elements of this array, going left to right. Returns the initial value
    *  if this array is empty.
    *
-   *  If `x,,1,,`, `x,,2,,`, ..., `x,,n,,` are the elements of this array, the
-   *  result is `op( op( ... op( op(z, x,,1,,), x,,2,,) ... ), x,,n,,)`.
+   *  If <code>x<sub>1</sub></code>, <code>x<sub>2</sub></code>, ..., <code>x<sub>n</sub></code> are the elements of this array, the
+   *  result is <code>op( op( ... op( op(z, x<sub>1</sub>), x<sub>2</sub>) ... ), x<sub>n</sub>)</code>.
    *
    *  @tparam   B       The result type of the binary operator.
    *  @param    z       An initial value.
@@ -912,8 +912,8 @@ final class ArrayOps[A](private val xs: Array[A]) extends AnyVal {
    *  the given initial value `z`, going right to left. Returns the initial
    *  value if this array is empty.
    *
-   *  If `x,,1,,`, `x,,2,,`, ..., `x,,n,,` are the elements of this array, the
-   *  result is `op(x,,1,,, op(x,,2,,, op( ... op(x,,n,,, z) ... )))`.
+   *  If <code>x<sub>1</sub></code>, <code>x<sub>2</sub></code>, ..., <code>x<sub>n</sub></code> are the elements of this array, the
+   *  result is <code>op(x<sub>1</sub>, op(x<sub>2</sub>, op( ... op(x<sub>n</sub>, z) ... )))</code>.
    *
    *  @tparam   B       The result type of the binary operator.
    *  @param    z       An initial value.

library/src/scala/collection/Iterable.scala

@@ -300,7 +300,7 @@ transparent trait IterableOps[+A, +CC[_], +C] extends Any with IterableOnce[A] w
 
   /** Returns a value class containing operations for comparing the size of this $coll to a test value.
    *
-   *  These operations are implemented in terms of [[sizeCompare(Int) `sizeCompare(Int)`]], and
+   *  These operations are implemented in terms of [[sizeCompare(Int) sizeCompare(Int)]], and
    *  allow the following more readable usages:
    *
    *  ```
@@ -891,7 +891,7 @@ object IterableOps {
   /** Operations for comparing the size of a collection to a test value.
    *
    *  These operations are implemented in terms of
-   *  [[scala.collection.IterableOps!.sizeCompare(Int):Int* `sizeCompare(Int)`]]
+   *  [[scala.collection.IterableOps!.sizeCompare(Int):Int* sizeCompare(Int)]]
    */
   final class SizeCompareOps private[collection](val it: IterableOps[?, AnyConstr, ?]) extends AnyVal {
     // CC Problem: if we add the logically needed `^`s to the `it` parameter and the