From 6c6e3249b6a33296b896d35a227bb89277d8ab28 Mon Sep 17 00:00:00 2001
From: Bill Venners <bill@artima.com>
Date: Wed, 20 May 2026 11:57:18 -0700
Subject: [PATCH] Add missing @param/@tparam/@return Scaladoc tags in
 scala.math (cleanup follow-up)

---
 library/src/scala/math/BigDecimal.scala       | 37 ++++++++++++
 library/src/scala/math/BigInt.scala           | 34 ++++++++++-
 library/src/scala/math/Equiv.scala            |  8 ++-
 library/src/scala/math/Integral.scala         |  1 +
 library/src/scala/math/Numeric.scala          |  2 +
 library/src/scala/math/Ordered.scala          |  2 +
 library/src/scala/math/Ordering.scala         | 14 +++++
 library/src/scala/math/PartialOrdering.scala  |  6 ++
 library/src/scala/math/PartiallyOrdered.scala |  1 +
 library/src/scala/math/package.scala          | 57 +++++++++++++++++++
 10 files changed, 158 insertions(+), 4 deletions(-)

diff --git a/library/src/scala/math/BigDecimal.scala b/library/src/scala/math/BigDecimal.scala
index 60623fb1f246..d826b4277368 100644
--- a/library/src/scala/math/BigDecimal.scala
+++ b/library/src/scala/math/BigDecimal.scala
@@ -52,6 +52,7 @@ object BigDecimal {
    *
    *  @param d the `Double` value to convert to a `BigDecimal`
    *  @param mc the precision and rounding mode for the conversion
+   *  @return a `BigDecimal` representing the decimal text form of `d`, rounded per `mc`
    */
   def decimal(d: Double, mc: MathContext): BigDecimal =
     new BigDecimal(new BigDec(java.lang.Double.toString(d), mc), mc)
@@ -59,6 +60,7 @@ object BigDecimal {
   /** Constructs a `BigDecimal` using the decimal text representation of `Double` value `d`.
    *
    *  @param d the `Double` value to convert to a `BigDecimal`
+   *  @return a `BigDecimal` representing the decimal text form of `d`, using the default `MathContext`
    */
   def decimal(d: Double): BigDecimal = decimal(d, defaultMathContext)
 
@@ -68,6 +70,7 @@ object BigDecimal {
    *
    *  @param f the `Float` value to convert to a `BigDecimal`
    *  @param mc the precision and rounding mode for the conversion
+   *  @return a `BigDecimal` representing the decimal text form of `f`, rounded per `mc`
    */
   def decimal(f: Float, mc: MathContext): BigDecimal =
     new BigDecimal(new BigDec(java.lang.Float.toString(f), mc), mc)
@@ -77,6 +80,7 @@ object BigDecimal {
    *  `0.1 != 0.1f`.
    *
    *  @param f the `Float` value to convert to a `BigDecimal`
+   *  @return a `BigDecimal` representing the decimal text form of `f`, using the default `MathContext`
    */
   def decimal(f: Float): BigDecimal = decimal(f, defaultMathContext)
 
@@ -85,6 +89,7 @@ object BigDecimal {
    *
    *  @param l the `Long` value to convert to a `BigDecimal`
    *  @param mc the precision and rounding mode for the conversion
+   *  @return a `BigDecimal` whose value equals `l`, rounded per `mc`
    */
   def decimal(l: Long, mc: MathContext): BigDecimal = apply(l, mc)
 
@@ -92,6 +97,7 @@ object BigDecimal {
   /** Constructs a `BigDecimal` from a `Long`.  This is identical to `BigDecimal(l)`.
    *
    *  @param l the `Long` value to convert to a `BigDecimal`
+   *  @return a `BigDecimal` whose value equals `l`, using the default `MathContext`
    */
   def decimal(l: Long): BigDecimal = apply(l)
 
@@ -99,6 +105,7 @@ object BigDecimal {
    *
    *  @param bd the `java.math.BigDecimal` to convert
    *  @param mc the precision and rounding mode for the conversion
+   *  @return a `BigDecimal` wrapping `bd` rounded per `mc`
    */
   def decimal(bd: BigDec, mc: MathContext): BigDecimal = new BigDecimal(bd.round(mc), mc)
 
@@ -110,6 +117,7 @@ object BigDecimal {
    *
    *  @param d the `Double` value whose binary fraction is expanded
    *  @param mc the precision and rounding mode for the conversion
+   *  @return a `BigDecimal` holding the binary expansion of `d`, rounded per `mc`
    */
   def binary(d: Double, mc: MathContext): BigDecimal = new BigDecimal(new BigDec(d, mc), mc)
 
@@ -118,6 +126,7 @@ object BigDecimal {
    *  Note: this also works correctly on converted `Float`s.
    *
    *  @param d the `Double` value whose binary fraction is expanded
+   *  @return a `BigDecimal` holding the binary expansion of `d`, using the default `MathContext`
    */
   def binary(d: Double): BigDecimal = binary(d, defaultMathContext)
 
@@ -126,6 +135,7 @@ object BigDecimal {
    *  the `java.math.BigDecimal` exactly, whichever is greater.
    *
    *  @param repr the `java.math.BigDecimal` to represent exactly
+   *  @return a `BigDecimal` exactly equal to `repr` with precision sufficient to preserve it
    */
   def exact(repr: BigDec): BigDecimal = {
     val mc =
@@ -139,12 +149,14 @@ object BigDecimal {
    *  necessary.  Note: this works correctly on converted `Float`s also.
    *
    *  @param d the `Double` value whose binary fraction is fully expanded
+   *  @return a `BigDecimal` exactly equal to the full decimal expansion of `d`'s binary fraction
    */
   def exact(d: Double): BigDecimal = exact(new BigDec(d))
 
   /** Constructs a `BigDecimal` that exactly represents a `BigInt`.
    *
    *  @param bi the `BigInt` value to represent exactly
+   *  @return a `BigDecimal` whose value exactly equals `bi`
    */
   def exact(bi: BigInt): BigDecimal = exact(new BigDec(bi.bigInteger))
 
@@ -153,6 +165,7 @@ object BigDecimal {
    *  represent a `Long`; this is equivalent to `apply`, `valueOf`, etc..
    *
    *  @param l the `Long` value to represent exactly
+   *  @return a `BigDecimal` exactly equal to `l`
    */
   def exact(l: Long): BigDecimal = apply(l)
 
@@ -160,6 +173,7 @@ object BigDecimal {
    *  specified in a `String`.
    *
    *  @param s the string representation of the number
+   *  @return a `BigDecimal` exactly equal to the value parsed from `s`
    */
   def exact(s: String): BigDecimal = exact(new BigDec(s))
 
@@ -167,6 +181,7 @@ object BigDecimal {
    *  specified in base 10 in a character array.
    *
    *  @param cs the character array containing the decimal representation
+   *  @return a `BigDecimal` exactly equal to the value parsed from `cs`
    */
   def exact(cs: Array[Char]): BigDecimal = exact(new BigDec(cs))
 
@@ -276,6 +291,7 @@ object BigDecimal {
    *  into a `BigDecimal`.
    *
    *  @param x the character array containing the decimal representation
+   *  @return a `BigDecimal` exactly equal to the value parsed from `x`
    */
   def apply(x: Array[Char]): BigDecimal = exact(x)
 
@@ -284,6 +300,7 @@ object BigDecimal {
    *
    *  @param x the character array containing the decimal representation
    *  @param mc the precision and rounding mode for creation of this value and future operations on it
+   *  @return the constructed `BigDecimal`
    */
   def apply(x: Array[Char], mc: MathContext): BigDecimal =
     new BigDecimal(new BigDec(x, mc), mc)
@@ -292,6 +309,7 @@ object BigDecimal {
    *  into a `BigDecimal`.
    *
    *  @param x the string representation of the decimal value
+   *  @return a `BigDecimal` exactly equal to the value parsed from `x`
    */
   def apply(x: String): BigDecimal = exact(x)
 
@@ -300,6 +318,7 @@ object BigDecimal {
    *
    *  @param x the string representation of the decimal value
    *  @param mc the precision and rounding mode for creation of this value and future operations on it
+   *  @return the constructed `BigDecimal`
    */
   def apply(x: String, mc: MathContext): BigDecimal =
     new BigDecimal(new BigDec(x, mc), mc)
@@ -346,24 +365,28 @@ object BigDecimal {
   /** Constructs a `BigDecimal` from a `java.math.BigDecimal`.
    *
    *  @param bd the `java.math.BigDecimal` to convert
+   *  @return a `BigDecimal` wrapping `bd` with the default `MathContext`
    */
   def apply(bd: BigDec): BigDecimal = new BigDecimal(bd, defaultMathContext)
 
   /** Implicit conversion from `Int` to `BigDecimal`.
    *
    *  @param i the `Int` value to convert
+   *  @return a `BigDecimal` whose value equals `i`
    */
   implicit def int2bigDecimal(i: Int): BigDecimal = apply(i)
 
   /** Implicit conversion from `Long` to `BigDecimal`.
    *
    *  @param l the `Long` value to convert
+   *  @return a `BigDecimal` whose value equals `l`
    */
   implicit def long2bigDecimal(l: Long): BigDecimal = apply(l)
 
   /** Implicit conversion from `Double` to `BigDecimal`.
    *
    *  @param d the `Double` value to convert
+   *  @return a `BigDecimal` representing the decimal text form of `d`
    */
   implicit def double2bigDecimal(d: Double): BigDecimal = decimal(d)
 
@@ -375,6 +398,7 @@ object BigDecimal {
   /** Implicit conversion from `java.math.BigDecimal` to `scala.BigDecimal`.
    *
    *  @param x the `java.math.BigDecimal` to convert
+   *  @return a `scala.BigDecimal` wrapping `x`, or `null` if `x` is `null`
    */
   implicit def javaBigDecimal2bigDecimal(x: BigDec): BigDecimal = mapNull(x, apply(x))
 }
@@ -474,6 +498,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
    *  disagree, `BigDecimal` will agree with the `Double` value
    *
    *  @param that the value to compare with this `BigDecimal`
+   *  @return `true` if `that` is numerically equal to this `BigDecimal` under the comparison rules described above, `false` otherwise
    */
   override def equals (that: Any): Boolean = that match {
     case that: BigDecimal     => this equals that
@@ -548,12 +573,14 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
   /** Compares this BigDecimal with the specified BigDecimal for equality.
    *
    *  @param that the `BigDecimal` to compare with
+   *  @return `true` if this and `that` represent the same numeric value, `false` otherwise
    */
   def equals (that: BigDecimal): Boolean = compare(that) == 0
 
   /** Compares this BigDecimal with the specified BigDecimal
    *
    *  @param that the `BigDecimal` to compare with
+   *  @return a negative number, zero, or a positive number if this is less than, equal to, or greater than `that`
    */
   def compare (that: BigDecimal): Int = this.bigDecimal.compareTo(that.bigDecimal)
 
@@ -594,6 +621,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
   /** Divide to Integral value.
    *
    *  @param that the `BigDecimal` divisor
+   *  @return the integer part of `this / that` as a `BigDecimal`
    */
   def quot (that: BigDecimal): BigDecimal =
     new BigDecimal(this.bigDecimal.divideToIntegralValue(that.bigDecimal, mc), mc)
@@ -601,6 +629,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
   /** Returns the minimum of this and that, or this if the two are equal
    *
    *  @param that the `BigDecimal` to compare with
+   *  @return the smaller of `this` and `that`, or `this` if they are equal
    */
   def min (that: BigDecimal): BigDecimal = (this compare that) match {
     case x if x <= 0 => this
@@ -610,6 +639,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
   /** Returns the maximum of this and that, or this if the two are equal
    *
    *  @param that the `BigDecimal` to compare with
+   *  @return the larger of `this` and `that`, or `this` if they are equal
    */
   def max (that: BigDecimal): BigDecimal = (this compare that) match {
     case x if x >= 0 => this
@@ -619,6 +649,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
   /** Remainder after dividing this by that.
    *
    *  @param that the `BigDecimal` divisor
+   *  @return the remainder of `this / that` as a `BigDecimal`
    */
   def remainder (that: BigDecimal): BigDecimal = new BigDecimal(this.bigDecimal.remainder(that.bigDecimal, mc), mc)
 
@@ -631,6 +662,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
   /** Returns a BigDecimal whose value is this ** n.
    *
    *  @param n the exponent to raise this `BigDecimal` to
+   *  @return a `BigDecimal` whose value is `this` raised to the power `n`
    */
   def pow (n: Int): BigDecimal = new BigDecimal(this.bigDecimal.pow(n, mc), mc)
 
@@ -661,6 +693,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
    *  preserving its own MathContext for future operations.
    *
    *  @param mc the `MathContext` specifying the precision and rounding mode
+   *  @return a `BigDecimal` rounded per `mc`, retaining this instance's own `MathContext`
    */
   def round(mc: MathContext): BigDecimal = {
     val r = this.bigDecimal.round(mc)
@@ -682,6 +715,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
   /** Returns a new BigDecimal based on the supplied MathContext, rounded as needed.
    *
    *  @param mc the new `MathContext` for precision and rounding
+   *  @return a `BigDecimal` rounded per `mc` and carrying `mc` as its `MathContext`
    */
   def apply(mc: MathContext): BigDecimal = new BigDecimal(this.bigDecimal.round(mc), mc)
 
@@ -689,6 +723,7 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
    *  numerically equal to this BigDecimal's.
    *
    *  @param scale the scale to set for this `BigDecimal`
+   *  @return a `BigDecimal` numerically equal to this one but with the requested `scale`
    */
   def setScale(scale: Int): BigDecimal =
     if (this.scale == scale) this
@@ -797,12 +832,14 @@ extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[
    *
    *  @param end the end value of the range (exclusive)
    *  @param step the increment between successive values in the range
+   *  @return an exclusive `NumericRange` from `this` to `end` by `step`
    */
   def until(end: BigDecimal, step: BigDecimal): NumericRange.Exclusive[BigDecimal] = Range.BigDecimal(this, end, step)
 
   /** Like `until`, but inclusive of the end value.
    *
    *  @param end the end value of the range (inclusive)
+   *  @return the partially constructed inclusive `NumericRange` (supply `step` via `by` to complete it)
    */
   def to(end: BigDecimal): Range.Partial[BigDecimal, NumericRange.Inclusive[BigDecimal]] =
     new Range.Partial(to(end, _))
diff --git a/library/src/scala/math/BigInt.scala b/library/src/scala/math/BigInt.scala
index 09db16d6d8a8..9f00489b1dfe 100644
--- a/library/src/scala/math/BigInt.scala
+++ b/library/src/scala/math/BigInt.scala
@@ -66,6 +66,7 @@ object BigInt {
    *  representation of a BigInt into a BigInt.
    *
    *  @param x the two's-complement big-endian binary representation of a `BigInt`
+   *  @return the `BigInt` represented by the given byte array
    */
   def apply(x: Array[Byte]): BigInt =
     apply(new BigInteger(x))
@@ -85,8 +86,9 @@ object BigInt {
    *  with the specified bitLength.
    *
    *  @param bitlength the bit length of the generated probable prime `BigInt`
-   *  @param certainty a measure of the uncertainty that the caller is willing to tolerate: the probability of primality exceeds `(1 - 1/2 ^ certainty)`
+   *  @param certainty a measure of the uncertainty that the caller is willing to tolerate: the probability of primality exceeds `(1 - 1/2 ^ certainty)`. The execution time is proportional to the value of this parameter.
    *  @param rnd the source of randomness used to generate the candidate
+   *  @return a randomly generated positive `BigInt` that is probably prime with the specified bit length
    */
   def apply(bitlength: Int, certainty: Int, rnd: scala.util.Random): BigInt =
     apply(new BigInteger(bitlength, certainty, rnd.self))
@@ -94,8 +96,9 @@ object BigInt {
   /** Constructs a randomly generated BigInt, uniformly distributed over the
    *  range `0` to `(2 ^ numBits - 1)`, inclusive.
    *
-   *  @param numbits the number of random bits used to generate the `BigInt`
+   *  @param numbits the maximum bit length of the generated `BigInt`; the result is uniformly distributed over `0` to `(2 ^ numbits - 1)`, inclusive
    *  @param rnd the source of randomness used for the generation
+   *  @return a randomly generated `BigInt` uniformly distributed over `0` to `(2 ^ numbits - 1)`, inclusive
    */
   def apply(numbits: Int, rnd: scala.util.Random): BigInt =
     apply(new BigInteger(numbits, rnd.self))
@@ -103,6 +106,7 @@ object BigInt {
   /** Translates the decimal String representation of a BigInt into a BigInt.
    *
    *  @param x the decimal string representation of the `BigInt`
+   *  @return the `BigInt` parsed from the given decimal string
    */
   def apply(x: String): BigInt =
     apply(new BigInteger(x))
@@ -112,6 +116,7 @@ object BigInt {
    *
    *  @param x the string representation of the `BigInt` in the specified radix
    *  @param radix the radix to use when parsing `x`
+   *  @return the `BigInt` parsed from `x` using the specified `radix`
    */
   def apply(x: String, radix: Int): BigInt =
     apply(new BigInteger(x, radix))
@@ -119,6 +124,7 @@ object BigInt {
   /** Translates a `java.math.BigInteger` into a BigInt.
    *
    *  @param x the `java.math.BigInteger` value to convert
+   *  @return a `BigInt` with the same value as `x`
    */
   def apply(x: BigInteger): BigInt = {
     if (x.bitLength <= 63) {
@@ -131,6 +137,7 @@ object BigInt {
    *
    *  @param bitLength the bit length of the returned probable prime `BigInt`
    *  @param rnd the source of randomness used to generate the candidate
+   *  @return a positive `BigInt` that is probably prime with the specified bit length
    */
   def probablePrime(bitLength: Int, rnd: scala.util.Random): BigInt =
     apply(BigInteger.probablePrime(bitLength, rnd.self))
@@ -138,12 +145,14 @@ object BigInt {
   /** Implicit conversion from `Int` to `BigInt`.
    *
    *  @param i the `Int` value to convert
+   *  @return a `BigInt` with the same value as `i`
    */
   implicit def int2bigInt(i: Int): BigInt = apply(i)
 
   /** Implicit conversion from `Long` to `BigInt`.
    *
    *  @param l the `Long` value to convert
+   *  @return a `BigInt` with the same value as `l`
    */
   implicit def long2bigInt(l: Long): BigInt = apply(l)
 
@@ -155,6 +164,7 @@ object BigInt {
   /** Implicit conversion from `java.math.BigInteger` to `scala.BigInt`.
    *
    *  @param x the `java.math.BigInteger` value to convert
+   *  @return a `scala.BigInt` with the same value as `x`, or `null` if `x` is `null`
    */
   implicit def javaBigInteger2bigInt(x: BigInteger): BigInt = mapNull(x, apply(x))
 
@@ -168,6 +178,7 @@ object BigInt {
    *
    *  @param a the first non-negative operand
    *  @param b the second non-negative operand
+   *  @return the greatest common divisor of `a` and `b`, or `0` if both are `0`
    */
   private def longGcd(a: Long, b: Long): Long = {
     // both a and b must be >= 0
@@ -324,6 +335,7 @@ final class BigInt private (
   /** Compares this BigInt with the specified BigInt for equality.
    *
    *  @param that the `BigInt` to compare against
+   *  @return `true` if this `BigInt` has the same value as `that`, `false` otherwise
    */
   def equals(that: BigInt): Boolean =
     if (this.longEncoding)
@@ -334,6 +346,7 @@ final class BigInt private (
   /** Compares this BigInt with the specified BigInt
    *
    *  @param that the `BigInt` to compare against
+   *  @return a negative number if `this` is less than `that`, zero if equal, or a positive number if greater
    */
   def compare(that: BigInt): Int =
     if (this.longEncoding) {
@@ -478,6 +491,7 @@ final class BigInt private (
   /** Returns the greatest common divisor of abs(this) and abs(that)
    *
    *  @param that the other value for computing the greatest common divisor
+   *  @return the greatest common divisor of `abs(this)` and `abs(that)` (defined as `0` when both are `0`)
    */
   def gcd(that: BigInt): BigInt =
     if (this.longEncoding) {
@@ -504,6 +518,7 @@ final class BigInt private (
   /** Returns a BigInt whose value is (this mod that).
    *  This method differs from `%` in that it always returns a non-negative BigInt.
    *  @param that A positive number
+   *  @return a non-negative `BigInt` whose value is `this mod that`
    */
   def mod(that: BigInt): BigInt =
     if (this.longEncoding && that.longEncoding && that._long > 0) {
@@ -514,6 +529,7 @@ final class BigInt private (
   /** Returns the minimum of this and that
    *
    *  @param that the value to compare with this `BigInt`
+   *  @return the smaller of this and `that`
    */
   def min(that: BigInt): BigInt =
     if (this <= that) this else that
@@ -521,6 +537,7 @@ final class BigInt private (
   /** Returns the maximum of this and that
    *
    *  @param that the value to compare with this `BigInt`
+   *  @return the larger of this and `that`
    */
   def max(that: BigInt): BigInt =
     if (this >= that) this else that
@@ -528,20 +545,23 @@ final class BigInt private (
   /** Returns a BigInt whose value is (<tt>this</tt> raised to the power of <tt>exp</tt>).
    *
    *  @param exp the exponent, must be non-negative
+   *  @return a `BigInt` whose value is `this` raised to the power of `exp`
    */
   def pow(exp: Int): BigInt = BigInt(this.bigInteger.pow(exp))
 
   /** Returns a BigInt whose value is
    *  (<tt>this</tt> raised to the power of <tt>exp</tt> modulo <tt>m</tt>).
    *
-   *  @param exp the exponent
+   *  @param exp the exponent; if negative, this operation uses the modular inverse of `this`, so `this` and `m` must be relatively prime
    *  @param m the modulus, must be positive
+   *  @return a `BigInt` whose value is `this` raised to the power of `exp` modulo `m`
    */
   def modPow(exp: BigInt, m: BigInt): BigInt = BigInt(this.bigInteger.modPow(exp.bigInteger, m.bigInteger))
 
   /** Returns a BigInt whose value is (the inverse of <tt>this</tt> modulo <tt>m</tt>).
    *
    *  @param m the modulus, must be positive
+   *  @return a `BigInt` whose value is the multiplicative inverse of `this` modulo `m`
    */
   def modInverse(m: BigInt): BigInt = BigInt(this.bigInteger.modInverse(m.bigInteger))
 
@@ -573,6 +593,7 @@ final class BigInt private (
   /** Returns true if and only if the designated bit is set.
    *
    *  @param n the zero-based index of the bit to test
+   *  @return `true` if the bit at position `n` is set, `false` otherwise
    */
   def testBit(n: Int): Boolean =
     if (longEncoding && n >= 0) {
@@ -585,6 +606,7 @@ final class BigInt private (
   /** Returns a BigInt whose value is equivalent to this BigInt with the designated bit set.
    *
    *  @param n the zero-based index of the bit to set
+   *  @return a `BigInt` equal to this with the bit at position `n` set to `1`
    */
   def setBit(n: Int): BigInt  = // note that we do not operate on the Long sign bit #63
     if (longEncoding && n <= 62 && n >= 0) BigInt(_long | (1L << n)) else BigInt(this.bigInteger.setBit(n))
@@ -592,6 +614,7 @@ final class BigInt private (
   /** Returns a BigInt whose value is equivalent to this BigInt with the designated bit cleared.
    *
    *  @param n the zero-based index of the bit to clear
+   *  @return a `BigInt` equal to this with the bit at position `n` cleared to `0`
    */
   def clearBit(n: Int): BigInt  = // note that we do not operate on the Long sign bit #63
     if (longEncoding && n <= 62 && n >= 0) BigInt(_long & ~(1L << n)) else BigInt(this.bigInteger.clearBit(n))
@@ -599,6 +622,7 @@ final class BigInt private (
   /** Returns a BigInt whose value is equivalent to this BigInt with the designated bit flipped.
    *
    *  @param n the zero-based index of the bit to flip
+   *  @return a `BigInt` equal to this with the bit at position `n` flipped
    */
   def flipBit(n: Int): BigInt  = // note that we do not operate on the Long sign bit #63
     if (longEncoding && n <= 62 && n >= 0) BigInt(_long ^ (1L << n)) else BigInt(this.bigInteger.flipBit(n))
@@ -631,11 +655,13 @@ final class BigInt private (
     } else this.bigInteger.bitCount()
 
   /** Returns true if this BigInt is probably prime, false if it's definitely composite.
+   *
    *  @param certainty  a measure of the uncertainty that the caller is willing to tolerate:
    *                    if the call returns true the probability that this BigInt is prime
    *                    exceeds (1 - 1/2 ^ certainty).
    *                    The execution time of this method is proportional to the value of
    *                    this parameter.
+   *  @return `true` if this `BigInt` is probably prime, `false` if it is definitely composite
    */
   def isProbablePrime(certainty: Int): Boolean = this.bigInteger.isProbablePrime(certainty)
 
@@ -705,6 +731,7 @@ final class BigInt private (
    *
    *  @param end the end value of the range (inclusive)
    *  @param step the distance between elements (defaults to 1)
+   *  @return the inclusive `NumericRange` from this to `end`
    */
   def to(end: BigInt, step: BigInt = BigInt(1)): NumericRange.Inclusive[BigInt] = Range.BigInt.inclusive(this, end, step)
 
@@ -714,6 +741,7 @@ final class BigInt private (
   /** Returns the String representation in the specified radix of this BigInt.
    *
    *  @param radix the radix to use in the string representation
+   *  @return the string representation of this `BigInt` in the specified `radix`
    */
   def toString(radix: Int): String = this.bigInteger.toString(radix)
 
diff --git a/library/src/scala/math/Equiv.scala b/library/src/scala/math/Equiv.scala
index 2c7b8d0123eb..1a75c21eff6e 100644
--- a/library/src/scala/math/Equiv.scala
+++ b/library/src/scala/math/Equiv.scala
@@ -39,6 +39,7 @@ trait Equiv[T] extends Any with Serializable {
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return `true` if `x` is equivalent to `y` under this relation, `false` otherwise
    */
   def equiv(x: T, y: T): Boolean
 }
@@ -104,12 +105,17 @@ object Equiv extends LowPriorityEquiv {
      *
      *  @tparam CC the collection type constructor, a subtype of `Seq` (e.g., `List`, `Vector`)
      *  @tparam T the element type of the collection
+     *  @param eqv the `Equiv` instance used to compare individual elements of type `T`
+     *  @return an `Equiv` for sequences of type `CC[T]` that compares them element-by-element using `eqv`
      */
     implicit def seqEquiv[CC[X] <: scala.collection.Seq[X], T](implicit eqv: Equiv[T]): Equiv[CC[T]] =
       new IterableEquiv[CC, T](eqv)
 
-    /** @tparam CC the collection type constructor, a subtype of `SortedSet`
+    /**
+     *  @tparam CC the collection type constructor, a subtype of `SortedSet`
      *  @tparam T the element type of the collection
+     *  @param eqv the `Equiv` instance used to compare individual elements of type `T`
+     *  @return an `Equiv` for sorted sets of type `CC[T]` that compares them element-by-element in iteration order using `eqv`
      */
     implicit def sortedSetEquiv[CC[X] <: scala.collection.SortedSet[X], T](implicit eqv: Equiv[T]): Equiv[CC[T]] =
       new IterableEquiv[CC, T](eqv)
diff --git a/library/src/scala/math/Integral.scala b/library/src/scala/math/Integral.scala
index 1c41fcdf8980..b06936b28045 100644
--- a/library/src/scala/math/Integral.scala
+++ b/library/src/scala/math/Integral.scala
@@ -39,6 +39,7 @@ object Integral {
      *  @tparam T the numeric type for which an `Integral` instance exists
      *  @param x the value to wrap with integral operator syntax (`/`, `%`, `/%`)
      *  @param num the implicit `Integral` instance for type `T`
+     *  @return an `IntegralOps` instance providing integral operators on `x`
      */
     implicit def infixIntegralOps[T](x: T)(implicit num: Integral[T]): Integral[T]#IntegralOps = new num.IntegralOps(x)
   }
diff --git a/library/src/scala/math/Numeric.scala b/library/src/scala/math/Numeric.scala
index 622c552a6657..9463a88189c0 100644
--- a/library/src/scala/math/Numeric.scala
+++ b/library/src/scala/math/Numeric.scala
@@ -33,6 +33,8 @@ object Numeric {
      *  @tparam T the numeric type for which a `Numeric` instance exists
      *  @param x the value to wrap with numeric infix operations
      *  @param num the implicit `Numeric` instance that provides the arithmetic operations
+     *
+     *  @return a `NumericOps` wrapper around `x` that exposes infix arithmetic operators and numeric conversion methods
      */
     implicit def infixNumericOps[T](x: T)(implicit num: Numeric[T]): Numeric[T]#NumericOps = new num.NumericOps(x)
   }
diff --git a/library/src/scala/math/Ordered.scala b/library/src/scala/math/Ordered.scala
index f7c42a0a4b43..0ffa768a8ad1 100644
--- a/library/src/scala/math/Ordered.scala
+++ b/library/src/scala/math/Ordered.scala
@@ -99,6 +99,7 @@ trait Ordered[A] extends Any with java.lang.Comparable[A] {
   /** Result of comparing `this` with operand `that`.
    *
    *  @param that the instance to compare against
+   *  @return a negative integer if `this < that`, zero if `this == that`, or a positive integer if `this > that`
    */
   def compareTo(that: A): Int = compare(that)
 }
@@ -109,6 +110,7 @@ object Ordered {
    *  @tparam T the type of the value to be wrapped as `Ordered`
    *  @param x the value to be converted to an `Ordered` instance
    *  @param ord the implicit `Ordering` instance used to perform comparisons
+   *  @return an `Ordered[T]` view of `x` that delegates comparisons to `ord`
    */
   implicit def orderingToOrdered[T](x: T)(implicit ord: Ordering[T]): Ordered[T] =
     new Ordered[T] { def compare(that: T): Int = ord.compare(x, that) }
diff --git a/library/src/scala/math/Ordering.scala b/library/src/scala/math/Ordering.scala
index 88ba27084cac..35af024e00d4 100644
--- a/library/src/scala/math/Ordering.scala
+++ b/library/src/scala/math/Ordering.scala
@@ -88,6 +88,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return `Some` containing the result of `compare(x, y)`, since `Ordering` always defines a comparison
    */
   def tryCompare(x: T, y: T): Some[Int] = Some(compare(x, y))
 
@@ -109,6 +110,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return `true` if `x` is less than or equal to `y` according to this ordering, `false` otherwise
    */
   override def lteq(x: T, y: T): Boolean = compare(x, y) <= 0
 
@@ -116,6 +118,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return `true` if `x` is greater than or equal to `y` according to this ordering, `false` otherwise
    */
   override def gteq(x: T, y: T): Boolean = compare(x, y) >= 0
 
@@ -123,6 +126,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return `true` if `x` is strictly less than `y` according to this ordering, `false` otherwise
    */
   override def lt(x: T, y: T): Boolean = compare(x, y) < 0
 
@@ -130,6 +134,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return `true` if `x` is strictly greater than `y` according to this ordering, `false` otherwise
    */
   override def gt(x: T, y: T): Boolean = compare(x, y) > 0
 
@@ -137,6 +142,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return `true` if `x` and `y` are considered equivalent under this ordering, `false` otherwise
    */
   override def equiv(x: T, y: T): Boolean = compare(x, y) == 0
 
@@ -145,6 +151,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
    *  @tparam U a subtype of `T`, used to preserve the specific type in the return value
    *  @param x the first candidate value
    *  @param y the second candidate value
+   *  @return the greater of `x` and `y` according to this ordering, returning `x` when they are equivalent
    */
   @uncheckedOverride def max[U <: T](x: U, y: U): U = if (gteq(x, y)) x else y
 
@@ -153,6 +160,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
    *  @tparam U a subtype of `T`, used to preserve the specific type in the return value
    *  @param x the first candidate value
    *  @param y the second candidate value
+   *  @return the lesser of `x` and `y` according to this ordering, returning `x` when they are equivalent
    */
   @uncheckedOverride def min[U <: T](x: U, y: U): U = if (lteq(x, y)) x else y
 
@@ -267,6 +275,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
    *  in `scala.math.Ordering.Ops`.
    *
    *  @param lhs the value to enrich with ordering operators
+   *  @return an `OrderingOps` wrapping `lhs` and providing infix comparison operators
    */
   implicit def mkOrderingOps(lhs: T): OrderingOps = new OrderingOps(lhs)
 }
@@ -283,6 +292,7 @@ trait LowPriorityOrderingImplicits {
    *
    *  @tparam A the type to be ordered, which must be convertible to `Comparable`
    *  @param asComparable the implicit conversion from `A` to `Comparable[? >: A]`
+   *  @return an `Ordering[A]` that compares values by delegating to their `Comparable.compareTo`
    */
   implicit def ordered[A](implicit asComparable: AsComparable[A]): Ordering[A] = new Ordering[A] {
     def compare(x: A, y: A): Int = asComparable(x).compareTo(y)
@@ -368,6 +378,9 @@ object Ordering extends LowPriorityOrderingImplicits {
      *  For instance `implicitly[Ordering[Any]]` diverges in its presence.
      *
      *  @tparam CC the higher-kinded type constructor for the sequence type, bounded by `scala.collection.Seq`
+     *  @tparam T the element type of the sequences being compared
+     *  @param ord the implicit `Ordering` used to compare elements of type `T`
+     *  @return an `Ordering[CC[T]]` that compares sequences lexicographically using `ord`
      */
     implicit def seqOrdering[CC[X] <: scala.collection.Seq[X], T](implicit ord: Ordering[T]): Ordering[CC[T]] =
       new IterableOrdering[CC, T](ord)
@@ -399,6 +412,7 @@ object Ordering extends LowPriorityOrderingImplicits {
    *
    *  @tparam T the type of objects to be ordered
    *  @param cmp a function that returns `true` if the first argument is less than the second
+   *  @return an `Ordering[T]` whose comparison is derived from `cmp`
    */
   def fromLessThan[T](cmp: (T, T) => Boolean): Ordering[T] = new Ordering[T] {
     def compare(x: T, y: T) = if (cmp(x, y)) -1 else if (cmp(y, x)) 1 else 0
diff --git a/library/src/scala/math/PartialOrdering.scala b/library/src/scala/math/PartialOrdering.scala
index b0155b41343a..9d79243f86d3 100644
--- a/library/src/scala/math/PartialOrdering.scala
+++ b/library/src/scala/math/PartialOrdering.scala
@@ -54,6 +54,7 @@ trait PartialOrdering[T] extends Equiv[T] {
    *
    *  @param x the first element to compare
    *  @param y the second element to compare
+   *  @return `Some(r)` where `r < 0` if `x < y`, `r == 0` if `x` equals `y`, and `r > 0` if `x > y`; `None` if `x` and `y` are incomparable
    */
   def tryCompare(x: T, y: T): Option[Int]
 
@@ -61,6 +62,7 @@ trait PartialOrdering[T] extends Equiv[T] {
    *
    *  @param x the first element to compare
    *  @param y the second element to compare
+   *  @return `true` if `x` is less than or equal to `y` in this ordering; `false` if `x > y` or if `x` and `y` are incomparable
    */
   def lteq(x: T, y: T): Boolean
 
@@ -68,6 +70,7 @@ trait PartialOrdering[T] extends Equiv[T] {
    *
    *  @param x the first element to compare
    *  @param y the second element to compare
+   *  @return `true` if `x` is greater than or equal to `y` in this ordering; `false` if `x < y` or if `x` and `y` are incomparable
    */
   def gteq(x: T, y: T): Boolean = lteq(y, x)
 
@@ -76,6 +79,7 @@ trait PartialOrdering[T] extends Equiv[T] {
    *
    *  @param x the first element to compare
    *  @param y the second element to compare
+   *  @return `true` if `x` is strictly less than `y` in this ordering; `false` otherwise, including when `x` and `y` are incomparable
    */
   def lt(x: T, y: T): Boolean = lteq(x, y) && !equiv(x, y)
 
@@ -84,6 +88,7 @@ trait PartialOrdering[T] extends Equiv[T] {
    *
    *  @param x the first element to compare
    *  @param y the second element to compare
+   *  @return `true` if `x` is strictly greater than `y` in this ordering; `false` otherwise, including when `x` and `y` are incomparable
    */
   def gt(x: T, y: T): Boolean = gteq(x, y) && !equiv(x, y)
 
@@ -91,6 +96,7 @@ trait PartialOrdering[T] extends Equiv[T] {
    *
    *  @param x the first element to compare
    *  @param y the second element to compare
+   *  @return `true` if `x` and `y` are equivalent under the ordering's induced equivalence relation
    */
   def equiv(x: T, y: T): Boolean = lteq(x,y) && lteq(y,x)
 
diff --git a/library/src/scala/math/PartiallyOrdered.scala b/library/src/scala/math/PartiallyOrdered.scala
index 096f1ea1d703..fa1ffebaf51b 100644
--- a/library/src/scala/math/PartiallyOrdered.scala
+++ b/library/src/scala/math/PartiallyOrdered.scala
@@ -32,6 +32,7 @@ trait PartiallyOrdered[+A] extends Any {
    *
    *  @tparam B a supertype of `A` for which an implicit conversion to `PartiallyOrdered[B]` exists
    *  @param that the value to compare against
+   *  @return `Some(x)` where `x < 0` means this is less than `that`, `x == 0` means they are equal, and `x > 0` means this is greater than `that`; `None` if the operands are not comparable
    */
   def tryCompareTo [B >: A: AsPartiallyOrdered](that: B): Option[Int]
 
diff --git a/library/src/scala/math/package.scala b/library/src/scala/math/package.scala
index c57b58361d1c..393171e8e1fa 100644
--- a/library/src/scala/math/package.scala
+++ b/library/src/scala/math/package.scala
@@ -109,36 +109,42 @@ package object math {
    *  @group trig
    *
    *  @param x the angle, in radians
+   *  @return the sine of `x`
    */
   def sin(x: Double): Double = java.lang.Math.sin(x)
   /**
    *  @group trig
    *
    *  @param x the angle, in radians
+   *  @return the cosine of `x`
    */
   def cos(x: Double): Double = java.lang.Math.cos(x)
   /**
    *  @group trig
    *
    *  @param x the angle, in radians
+   *  @return the tangent of `x`
    */
   def tan(x: Double): Double = java.lang.Math.tan(x)
   /**
    *  @group trig
    *
    *  @param x the value whose arc sine is to be returned
+   *  @return the arc sine of `x`, in radians, in the range -π/2 through π/2
    */
   def asin(x: Double): Double = java.lang.Math.asin(x)
   /**
    *  @group trig
    *
    *  @param x the value whose arc cosine is to be returned
+   *  @return the arc cosine of `x`, in radians, in the range 0 through π
    */
   def acos(x: Double): Double = java.lang.Math.acos(x)
   /**
    *  @group trig
    *
    *  @param x the value whose arc tangent is to be returned
+   *  @return the arc tangent of `x`, in radians, in the range -π/2 through π/2
    */
   def atan(x: Double): Double = java.lang.Math.atan(x)
 
@@ -193,12 +199,14 @@ package object math {
    *  @group rounding
    *
    *  @param x the value to be rounded up
+   *  @return the smallest `Double` value greater than or equal to `x` that is equal to a mathematical integer
    */
   def ceil(x: Double): Double  = java.lang.Math.ceil(x)
   /**
    *  @group rounding
    *
    *  @param x the value to be rounded down
+   *  @return the largest `Double` value less than or equal to `x` that is equal to a mathematical integer
    */
   def floor(x: Double): Double = java.lang.Math.floor(x)
 
@@ -240,24 +248,28 @@ package object math {
    *  @group abs
    *
    *  @param x the value whose absolute value is to be determined
+   *  @return the absolute value of `x`
    */
   def abs(x: Int): Int       = java.lang.Math.abs(x)
   /**
    *  @group abs
    *
    *  @param x the value whose absolute value is to be determined
+   *  @return the absolute value of `x`
    */
   def abs(x: Long): Long     = java.lang.Math.abs(x)
   /**
    *  @group abs
    *
    *  @param x the value whose absolute value is to be determined
+   *  @return the absolute value of `x`
    */
   def abs(x: Float): Float   = java.lang.Math.abs(x)
   /**
    *  @group abs
    *
    *  @param x the value whose absolute value is to be determined
+   *  @return the absolute value of `x`
    */
   def abs(x: Double): Double = java.lang.Math.abs(x)
 
@@ -266,6 +278,7 @@ package object math {
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return the larger of `x` and `y`
    */
   def max(x: Int, y: Int): Int          = java.lang.Math.max(x, y)
   /**
@@ -273,6 +286,7 @@ package object math {
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return the larger of `x` and `y`
    */
   def max(x: Long, y: Long): Long       = java.lang.Math.max(x, y)
   /**
@@ -280,6 +294,7 @@ package object math {
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return the larger of `x` and `y`
    */
   def max(x: Float, y: Float): Float    = java.lang.Math.max(x, y)
   /**
@@ -287,6 +302,7 @@ package object math {
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return the larger of `x` and `y`
    */
   def max(x: Double, y: Double): Double = java.lang.Math.max(x, y)
 
@@ -295,6 +311,7 @@ package object math {
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return the smaller of `x` and `y`
    */
   def min(x: Int, y: Int): Int          = java.lang.Math.min(x, y)
   /**
@@ -302,6 +319,7 @@ package object math {
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return the smaller of `x` and `y`
    */
   def min(x: Long, y: Long): Long       = java.lang.Math.min(x, y)
   /**
@@ -309,6 +327,7 @@ package object math {
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return the smaller of `x` and `y`
    */
   def min(x: Float, y: Float): Float    = java.lang.Math.min(x, y)
   /**
@@ -316,6 +335,7 @@ package object math {
    *
    *  @param x the first value to compare
    *  @param y the second value to compare
+   *  @return the smaller of `x` and `y`
    */
   def min(x: Double, y: Double): Double = java.lang.Math.min(x, y)
 
@@ -324,6 +344,7 @@ package object math {
    *  @note Forwards to [[java.lang.Integer]]
    *
    *  @param x the value whose signum is to be computed
+   *  @return `-1` if `x` is negative, `0` if `x` is zero, or `1` if `x` is positive
    */
   def signum(x: Int): Int       = java.lang.Integer.signum(x)
   /**
@@ -331,18 +352,21 @@ package object math {
    *  @note Forwards to [[java.lang.Long]]
    *
    *  @param x the value whose signum is to be computed
+   *  @return `-1` if `x` is negative, `0` if `x` is zero, or `1` if `x` is positive
    */
   def signum(x: Long): Long     = java.lang.Long.signum(x)
   /**
    *  @group signs
    *
    *  @param x the value whose signum is to be computed
+   *  @return `-1` if `x` is negative, `0` if `x` is zero, or `1` if `x` is positive
    */
   def signum(x: Float): Float   = java.lang.Math.signum(x)
   /**
    *  @group signs
    *
    *  @param x the value whose signum is to be computed
+   *  @return `-1` if `x` is negative, `0` if `x` is zero, or `1` if `x` is positive
    */
   def signum(x: Double): Double = java.lang.Math.signum(x)
 
@@ -351,6 +375,7 @@ package object math {
    *
    *  @param x the dividend
    *  @param y the divisor
+   *  @return the largest value that is less than or equal to the algebraic quotient `x / y`
    */
   def floorDiv(x: Int, y: Int): Int = java.lang.Math.floorDiv(x, y)
 
@@ -359,6 +384,7 @@ package object math {
    *
    *  @param x the dividend
    *  @param y the divisor
+   *  @return the largest value that is less than or equal to the algebraic quotient `x / y`
    */
   def floorDiv(x: Long, y: Long): Long = java.lang.Math.floorDiv(x, y)
 
@@ -367,6 +393,7 @@ package object math {
    *
    *  @param x the dividend
    *  @param y the divisor
+   *  @return the floor modulus `x - (floorDiv(x, y) * y)`
    */
   def floorMod(x: Int, y: Int): Int = java.lang.Math.floorMod(x, y)
 
@@ -375,6 +402,7 @@ package object math {
    *
    *  @param x the dividend
    *  @param y the divisor
+   *  @return the floor modulus `x - (floorDiv(x, y) * y)`
    */
   def floorMod(x: Long, y: Long): Long = java.lang.Math.floorMod(x, y)
 
@@ -383,6 +411,7 @@ package object math {
    *
    *  @param magnitude the value providing the magnitude of the result
    *  @param sign the value providing the sign of the result
+   *  @return a value with the magnitude of `magnitude` and the sign of `sign`
    */
   def copySign(magnitude: Double, sign: Double): Double = java.lang.Math.copySign(magnitude, sign)
 
@@ -391,6 +420,7 @@ package object math {
    *
    *  @param magnitude the value providing the magnitude of the result
    *  @param sign the value providing the sign of the result
+   *  @return a value with the magnitude of `magnitude` and the sign of `sign`
    */
   def copySign(magnitude: Float, sign: Float): Float = java.lang.Math.copySign(magnitude, sign)
 
@@ -399,6 +429,7 @@ package object math {
    *
    *  @param start the starting floating-point value
    *  @param direction the value indicating which of `start`'s neighbors should be returned
+   *  @return the floating-point number adjacent to `start` in the direction of `direction`, or `direction` if `start` equals `direction`
    */
   def nextAfter(start: Double, direction: Double): Double = java.lang.Math.nextAfter(start, direction)
 
@@ -407,6 +438,7 @@ package object math {
    *
    *  @param start the starting floating-point value
    *  @param direction the value indicating which of `start`'s neighbors should be returned
+   *  @return the floating-point number adjacent to `start` in the direction of `direction`, or `direction` if `start` equals `direction`
    */
   def nextAfter(start: Float, direction: Double): Float = java.lang.Math.nextAfter(start, direction)
 
@@ -414,6 +446,7 @@ package object math {
    *  @group adjacent-float
    *
    *  @param d the starting floating-point value
+   *  @return the floating-point value adjacent to `d` in the direction of positive infinity
    */
   def nextUp(d: Double): Double = java.lang.Math.nextUp(d)
 
@@ -421,6 +454,7 @@ package object math {
    *  @group adjacent-float
    *
    *  @param f the starting floating-point value
+   *  @return the floating-point value adjacent to `f` in the direction of positive infinity
    */
   def nextUp(f: Float): Float = java.lang.Math.nextUp(f)
 
@@ -428,6 +462,7 @@ package object math {
    *  @group adjacent-float
    *
    *  @param d the starting floating-point value
+   *  @return the floating-point value adjacent to `d` in the direction of negative infinity
    */
   def nextDown(d: Double): Double = java.lang.Math.nextDown(d)
 
@@ -435,6 +470,7 @@ package object math {
    *  @group adjacent-float
    *
    *  @param f the starting floating-point value
+   *  @return the floating-point value adjacent to `f` in the direction of negative infinity
    */
   def nextDown(f: Float): Float = java.lang.Math.nextDown(f)
 
@@ -443,6 +479,7 @@ package object math {
    *
    *  @param d the value to be scaled by a power of two
    *  @param scaleFactor the power of 2 used to scale `d`
+   *  @return `d` × 2^`scaleFactor`^, correctly rounded
    */
   def scalb(d: Double, scaleFactor: Int): Double = java.lang.Math.scalb(d, scaleFactor)
 
@@ -451,6 +488,7 @@ package object math {
    *
    *  @param f the value to be scaled by a power of two
    *  @param scaleFactor the power of 2 used to scale `f`
+   *  @return `f` × 2^`scaleFactor`^, correctly rounded
    */
   def scalb(f: Float, scaleFactor: Int): Float = java.lang.Math.scalb(f, scaleFactor)
 
@@ -501,6 +539,7 @@ package object math {
    *  @group explog
    *
    *  @param x the exponent to raise `e` to in the computation of `e`^`x`^ - 1
+   *  @return the value `e`^`x`^ - 1
    */
   def expm1(x: Double): Double = java.lang.Math.expm1(x)
 
@@ -508,6 +547,7 @@ package object math {
    *  @group explog
    *
    *  @param f the `Float` value whose unbiased exponent is to be extracted
+   *  @return the unbiased exponent used in the representation of `f`
    */
   def getExponent(f: Float): Int = java.lang.Math.getExponent(f)
 
@@ -515,6 +555,7 @@ package object math {
    *  @group explog
    *
    *  @param d the `Double` value whose unbiased exponent is to be extracted
+   *  @return the unbiased exponent used in the representation of `d`
    */
   def getExponent(d: Double): Int = java.lang.Math.getExponent(d)
 
@@ -534,6 +575,7 @@ package object math {
    *  @group explog
    *
    *  @param x the value for which to compute `ln(1 + x)`
+   *  @return the natural logarithm of `1 + x`
    */
   def log1p(x: Double): Double = java.lang.Math.log1p(x)
 
@@ -541,6 +583,7 @@ package object math {
    *  @group explog
    *
    *  @param x the value whose base 10 logarithm is to be computed
+   *  @return the base 10 logarithm of `x`
    */
   def log10(x: Double): Double = java.lang.Math.log10(x)
 
@@ -552,6 +595,7 @@ package object math {
    *  @group hyperbolic
    *
    *  @param x the value whose hyperbolic sine is to be returned
+   *  @return the hyperbolic sine of `x`
    */
   def sinh(x: Double): Double = java.lang.Math.sinh(x)
 
@@ -559,6 +603,7 @@ package object math {
    *  @group hyperbolic
    *
    *  @param x the value whose hyperbolic cosine is to be returned
+   *  @return the hyperbolic cosine of `x`
    */
   def cosh(x: Double): Double = java.lang.Math.cosh(x)
 
@@ -566,6 +611,7 @@ package object math {
    *  @group hyperbolic
    *
    *  @param x the value whose hyperbolic tangent is to be returned
+   *  @return the hyperbolic tangent of `x`
    */
   def tanh(x: Double):Double = java.lang.Math.tanh(x)
 
@@ -577,6 +623,7 @@ package object math {
    *  @group ulp
    *
    *  @param x the `Double` value whose ulp is to be returned
+   *  @return the positive distance between `x` and the `Double` value next larger in magnitude
    */
   def ulp(x: Double): Double = java.lang.Math.ulp(x)
 
@@ -584,6 +631,7 @@ package object math {
    *  @group ulp
    *
    *  @param x the `Float` value whose ulp is to be returned
+   *  @return the positive distance between `x` and the `Float` value next larger in magnitude
    */
   def ulp(x: Float): Float = java.lang.Math.ulp(x)
 
@@ -592,6 +640,7 @@ package object math {
    *
    *  @param x the dividend value
    *  @param y the divisor value
+   *  @return the remainder of `x` divided by `y` as defined by the IEEE 754 standard
    */
   def IEEEremainder(x: Double, y: Double): Double = java.lang.Math.IEEEremainder(x, y)
 
@@ -604,6 +653,7 @@ package object math {
    *
    *  @param x the first addend
    *  @param y the second addend
+   *  @return the sum `x + y`, throwing `ArithmeticException` if the result overflows
    */
   def addExact(x: Int, y: Int): Int = java.lang.Math.addExact(x, y)
 
@@ -612,6 +662,7 @@ package object math {
    *
    *  @param x the first addend
    *  @param y the second addend
+   *  @return the sum `x + y`, throwing `ArithmeticException` if the result overflows
    */
   def addExact(x: Long, y: Long): Long = java.lang.Math.addExact(x, y)
 
@@ -620,6 +671,7 @@ package object math {
    *
    *  @param x the minuend
    *  @param y the subtrahend
+   *  @return the difference `x - y`, throwing `ArithmeticException` if the result overflows
    */
   def subtractExact(x: Int, y: Int): Int = java.lang.Math.subtractExact(x, y)
 
@@ -628,6 +680,7 @@ package object math {
    *
    *  @param x the minuend
    *  @param y the subtrahend
+   *  @return the difference `x - y`, throwing `ArithmeticException` if the result overflows
    */
   def subtractExact(x: Long, y: Long): Long = java.lang.Math.subtractExact(x, y)
 
@@ -636,6 +689,7 @@ package object math {
    *
    *  @param x the first factor
    *  @param y the second factor
+   *  @return the product `x * y`, throwing `ArithmeticException` if the result overflows
    */
   def multiplyExact(x: Int, y: Int): Int = java.lang.Math.multiplyExact(x, y)
 
@@ -644,6 +698,7 @@ package object math {
    *
    *  @param x the first factor
    *  @param y the second factor
+   *  @return the product `x * y`, throwing `ArithmeticException` if the result overflows
    */
   def multiplyExact(x: Long, y: Long): Long = java.lang.Math.multiplyExact(x, y)
 
@@ -651,6 +706,7 @@ package object math {
    *  @group exact
    *
    *  @param x the value to be incremented
+   *  @return `x + 1`, throwing `ArithmeticException` if the result overflows
    */
   def incrementExact(x: Int): Int = java.lang.Math.incrementExact(x)
 
@@ -693,6 +749,7 @@ package object math {
    *  @group exact
    *
    *  @param x the `Long` value to convert to an `Int`
+   *  @return `x` as an `Int`, throwing `ArithmeticException` if the value overflows an `Int`
    */
   def toIntExact(x: Long): Int = java.lang.Math.toIntExact(x)