Improve math docs

Add links from log to ln, log2, log10.
Format lists in docs so that they are pretty in quick doc window.

js/js.libraries/src/core/math.kt

@@ -34,7 +34,6 @@ public const val E: Double = 2.718281828459045
 /** Computes the sine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `sin(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -44,7 +43,6 @@ public inline fun sin(a: Double): Double = nativeMath.sin(a)
 /** Computes the cosine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `cos(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -54,7 +52,6 @@ public inline fun cos(a: Double): Double = nativeMath.cos(a)
 /** Computes the tangent of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `tan(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -118,7 +115,6 @@ public inline fun atan2(y: Double, x: Double): Double = nativeMath.atan2(y, x)
  * Computes the hyperbolic sine of the value [a].
  *
  * Special cases:
- *
  *   - `sinh(NaN)` is `NaN`
  *   - `sinh(+Inf)` is `+Inf`
  *   - `sinh(-Inf)` is `-Inf`
@@ -131,7 +127,6 @@ public inline fun sinh(a: Double): Double = nativeMath.sinh(a)
  * Computes the hyperbolic cosine of the value [a].
  *
  * Special cases:
- *
  *   - `cosh(NaN)` is `NaN`
  *   - `cosh(+Inf|-Inf)` is `+Inf`
  */
@@ -143,7 +138,6 @@ public inline fun cosh(a: Double): Double = nativeMath.cosh(a)
  * Computes the hyperbolic tangent of the value [a].
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(+Inf)` is `1.0`
  *   - `tanh(-Inf)` is `-1.0`
@@ -158,7 +152,6 @@ public inline fun tanh(a: Double): Double = nativeMath.tanh(a)
  * The returned value is `x` such that `sinh(x) == a`.
  *
  * Special cases:
- *
  *   - `asinh(NaN)` is `NaN`
  *   - `asinh(+Inf)` is `+Inf`
  *   - `asinh(-Inf)` is `-Inf`
@@ -173,7 +166,6 @@ public inline fun asinh(a: Double): Double = nativeMath.asinh(a)
  * The returned value is positive `x` such that `cosh(x) == a`.
  *
  * Special cases:
- *
  *   - `acosh(NaN)` is `NaN`
  *   - `acosh(x)` is `NaN` when `x < 1`
  *   - `acosh(+Inf)` is `+Inf`
@@ -188,7 +180,6 @@ public inline fun acosh(a: Double): Double = nativeMath.acosh(a)
  * The returned value is `x` such that `tanh(x) == a`.
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
  *   - `tanh(1.0)` is `+Inf`
@@ -256,6 +247,8 @@ public inline fun expm1(a: Double): Double = nativeMath.expm1(a)
  *   - `log(+Inf, +Inf)` is `NaN`
  *   - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
  *   - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
+ *
+ * See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
  */
 @SinceKotlin("1.2")
 public fun log(a: Double, base: Double): Double {
@@ -576,7 +569,6 @@ public fun Double.roundToLong(): Long = when {
 /** Computes the sine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `sin(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -586,7 +578,6 @@ public inline fun sin(a: Float): Float = nativeMath.sin(a.toDouble()).toFloat()
 /** Computes the cosine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `cos(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -596,7 +587,6 @@ public inline fun cos(a: Float): Float = nativeMath.cos(a.toDouble()).toFloat()
 /** Computes the tangent of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `tan(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -660,7 +650,6 @@ public inline fun atan2(y: Float, x: Float): Float = nativeMath.atan2(y.toDouble
  * Computes the hyperbolic sine of the value [a].
  *
  * Special cases:
- *
  *   - `sinh(NaN)` is `NaN`
  *   - `sinh(+Inf)` is `+Inf`
  *   - `sinh(-Inf)` is `-Inf`
@@ -673,7 +662,6 @@ public inline fun sinh(a: Float): Float = nativeMath.sinh(a.toDouble()).toFloat(
  * Computes the hyperbolic cosine of the value [a].
  *
  * Special cases:
- *
  *   - `cosh(NaN)` is `NaN`
  *   - `cosh(+Inf|-Inf)` is `+Inf`
  */
@@ -685,7 +673,6 @@ public inline fun cosh(a: Float): Float = nativeMath.cosh(a.toDouble()).toFloat(
  * Computes the hyperbolic tangent of the value [a].
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(+Inf)` is `1.0`
  *   - `tanh(-Inf)` is `-1.0`
@@ -700,7 +687,6 @@ public inline fun tanh(a: Float): Float = nativeMath.tanh(a.toDouble()).toFloat(
  * The returned value is `x` such that `sinh(x) == a`.
  *
  * Special cases:
- *
  *   - `asinh(NaN)` is `NaN`
  *   - `asinh(+Inf)` is `+Inf`
  *   - `asinh(-Inf)` is `-Inf`
@@ -715,7 +701,6 @@ public inline fun asinh(a: Float): Float = nativeMath.asinh(a.toDouble()).toFloa
  * The returned value is positive `x` such that `cosh(x) == a`.
  *
  * Special cases:
- *
  *   - `acosh(NaN)` is `NaN`
  *   - `acosh(x)` is `NaN` when `x < 1`
  *   - `acosh(+Inf)` is `+Inf`
@@ -730,7 +715,6 @@ public inline fun acosh(a: Float): Float = nativeMath.acosh(a.toDouble()).toFloa
  * The returned value is `x` such that `tanh(x) == a`.
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
  *   - `tanh(1.0)` is `+Inf`
@@ -798,6 +782,8 @@ public inline fun expm1(a: Float): Float = nativeMath.expm1(a.toDouble()).toFloa
  *   - `log(+Inf, +Inf)` is `NaN`
  *   - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
  *   - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
+ *
+ * See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
  */
 @SinceKotlin("1.2")
 @InlineOnly

libraries/stdlib/common/src/kotlin/MathH.kt

@@ -32,7 +32,6 @@ public const val E: Double = 2.718281828459045
 /** Computes the sine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `sin(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -41,7 +40,6 @@ public expect fun sin(a: Double): Double
 /** Computes the cosine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `cos(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -50,7 +48,6 @@ public expect fun cos(a: Double): Double
 /** Computes the tangent of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `tan(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -109,7 +106,6 @@ public expect fun atan2(y: Double, x: Double): Double
  * Computes the hyperbolic sine of the value [a].
  *
  * Special cases:
- *
  *   - `sinh(NaN)` is `NaN`
  *   - `sinh(+Inf)` is `+Inf`
  *   - `sinh(-Inf)` is `-Inf`
@@ -121,7 +117,6 @@ public expect fun sinh(a: Double): Double
  * Computes the hyperbolic cosine of the value [a].
  *
  * Special cases:
- *
  *   - `cosh(NaN)` is `NaN`
  *   - `cosh(+Inf|-Inf)` is `+Inf`
  */
@@ -132,7 +127,6 @@ public expect fun cosh(a: Double): Double
  * Computes the hyperbolic tangent of the value [a].
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(+Inf)` is `1.0`
  *   - `tanh(-Inf)` is `-1.0`
@@ -146,7 +140,6 @@ public expect fun tanh(a: Double): Double
  * The returned value is `x` such that `sinh(x) == a`.
  *
  * Special cases:
- *
  *   - `asinh(NaN)` is `NaN`
  *   - `asinh(+Inf)` is `+Inf`
  *   - `asinh(-Inf)` is `-Inf`
@@ -160,7 +153,6 @@ public expect fun asinh(a: Double): Double
  * The returned value is positive `x` such that `cosh(x) == a`.
  *
  * Special cases:
- *
  *   - `acosh(NaN)` is `NaN`
  *   - `acosh(x)` is `NaN` when `x < 1`
  *   - `acosh(+Inf)` is `+Inf`
@@ -174,7 +166,6 @@ public expect fun acosh(a: Double): Double
  * The returned value is `x` such that `tanh(x) == a`.
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
  *   - `tanh(1.0)` is `+Inf`
@@ -237,6 +228,8 @@ public expect fun expm1(a: Double): Double
  *   - `log(+Inf, +Inf)` is `NaN`
  *   - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
  *   - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
+ *
+ * See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
  */
 @SinceKotlin("1.2")
 public expect fun log(a: Double, base: Double): Double
@@ -497,7 +490,6 @@ public expect fun Double.roundToLong(): Long
 /** Computes the sine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `sin(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -506,7 +498,6 @@ public expect fun sin(a: Float): Float
 /** Computes the cosine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `cos(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -515,7 +506,6 @@ public expect fun cos(a: Float): Float
 /** Computes the tangent of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `tan(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -574,7 +564,6 @@ public expect fun atan2(y: Float, x: Float): Float
  * Computes the hyperbolic sine of the value [a].
  *
  * Special cases:
- *
  *   - `sinh(NaN)` is `NaN`
  *   - `sinh(+Inf)` is `+Inf`
  *   - `sinh(-Inf)` is `-Inf`
@@ -586,7 +575,6 @@ public expect fun sinh(a: Float): Float
  * Computes the hyperbolic cosine of the value [a].
  *
  * Special cases:
- *
  *   - `cosh(NaN)` is `NaN`
  *   - `cosh(+Inf|-Inf)` is `+Inf`
  */
@@ -597,7 +585,6 @@ public expect fun cosh(a: Float): Float
  * Computes the hyperbolic tangent of the value [a].
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(+Inf)` is `1.0`
  *   - `tanh(-Inf)` is `-1.0`
@@ -611,7 +598,6 @@ public expect fun tanh(a: Float): Float
  * The returned value is `x` such that `sinh(x) == a`.
  *
  * Special cases:
- *
  *   - `asinh(NaN)` is `NaN`
  *   - `asinh(+Inf)` is `+Inf`
  *   - `asinh(-Inf)` is `-Inf`
@@ -625,7 +611,6 @@ public expect fun asinh(a: Float): Float
  * The returned value is positive `x` such that `cosh(x) == a`.
  *
  * Special cases:
- *
  *   - `acosh(NaN)` is `NaN`
  *   - `acosh(x)` is `NaN` when `x < 1`
  *   - `acosh(+Inf)` is `+Inf`
@@ -639,7 +624,6 @@ public expect fun acosh(a: Float): Float
  * The returned value is `x` such that `tanh(x) == a`.
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
  *   - `tanh(1.0)` is `+Inf`
@@ -702,6 +686,8 @@ public expect fun expm1(a: Float): Float
  *   - `log(+Inf, +Inf)` is `NaN`
  *   - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
  *   - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
+ *
+ * See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
  */
 @SinceKotlin("1.2")
 public expect fun log(a: Float, base: Float): Float

libraries/stdlib/src/kotlin/util/MathJVM.kt

@@ -43,7 +43,6 @@ private val upper_taylor_n_bound = 1 / taylor_n_bound
 /** Computes the sine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `sin(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -53,7 +52,6 @@ public inline fun sin(a: Double): Double = nativeMath.sin(a)
 /** Computes the cosine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `cos(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -63,7 +61,6 @@ public inline fun cos(a: Double): Double = nativeMath.cos(a)
 /** Computes the tangent of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `tan(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -127,7 +124,6 @@ public inline fun atan2(y: Double, x: Double): Double = nativeMath.atan2(y, x)
  * Computes the hyperbolic sine of the value [a].
  *
  * Special cases:
- *
  *   - `sinh(NaN)` is `NaN`
  *   - `sinh(+Inf)` is `+Inf`
  *   - `sinh(-Inf)` is `-Inf`
@@ -140,7 +136,6 @@ public inline fun sinh(a: Double): Double = nativeMath.sinh(a)
  * Computes the hyperbolic cosine of the value [a].
  *
  * Special cases:
- *
  *   - `cosh(NaN)` is `NaN`
  *   - `cosh(+Inf|-Inf)` is `+Inf`
  */
@@ -152,7 +147,6 @@ public inline fun cosh(a: Double): Double = nativeMath.cosh(a)
  * Computes the hyperbolic tangent of the value [a].
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(+Inf)` is `1.0`
  *   - `tanh(-Inf)` is `-1.0`
@@ -171,7 +165,6 @@ public inline fun tanh(a: Double): Double = nativeMath.tanh(a)
  * The returned value is `x` such that `sinh(x) == a`.
  *
  * Special cases:
- *
  *   - `asinh(NaN)` is `NaN`
  *   - `asinh(+Inf)` is `+Inf`
  *   - `asinh(-Inf)` is `-Inf`
@@ -210,7 +203,6 @@ public fun asinh(a: Double): Double =
  * The returned value is positive `x` such that `cosh(x) == a`.
  *
  * Special cases:
- *
  *   - `acosh(NaN)` is `NaN`
  *   - `acosh(x)` is `NaN` when `x < 1`
  *   - `acosh(+Inf)` is `+Inf`
@@ -246,7 +238,6 @@ public fun acosh(a: Double): Double =
  * The returned value is `x` such that `tanh(x) == a`.
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
  *   - `tanh(1.0)` is `+Inf`
@@ -322,6 +313,8 @@ public inline fun expm1(a: Double): Double = nativeMath.expm1(a)
  *   - `log(+Inf, +Inf)` is `NaN`
  *   - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
  *   - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
+ *
+ * See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
  */
 @SinceKotlin("1.2")
 public fun log(a: Double, base: Double): Double {
@@ -631,7 +624,6 @@ public fun Double.roundToLong(): Long = if (isNaN()) throw IllegalArgumentExcept
 /** Computes the sine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `sin(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -641,7 +633,6 @@ public inline fun sin(a: Float): Float = nativeMath.sin(a.toDouble()).toFloat()
 /** Computes the cosine of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `cos(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -651,7 +642,6 @@ public inline fun cos(a: Float): Float = nativeMath.cos(a.toDouble()).toFloat()
 /** Computes the tangent of the angle [a] given in radians.
  *
  *  Special cases:
- *
  *   - `tan(NaN|+Inf|-Inf)` is `NaN`
  */
 @SinceKotlin("1.2")
@@ -715,7 +705,6 @@ public inline fun atan2(y: Float, x: Float): Float = nativeMath.atan2(y.toDouble
  * Computes the hyperbolic sine of the value [a].
  *
  * Special cases:
- *
  *   - `sinh(NaN)` is `NaN`
  *   - `sinh(+Inf)` is `+Inf`
  *   - `sinh(-Inf)` is `-Inf`
@@ -728,7 +717,6 @@ public inline fun sinh(a: Float): Float = nativeMath.sinh(a.toDouble()).toFloat(
  * Computes the hyperbolic cosine of the value [a].
  *
  * Special cases:
- *
  *   - `cosh(NaN)` is `NaN`
  *   - `cosh(+Inf|-Inf)` is `+Inf`
  */
@@ -740,7 +728,6 @@ public inline fun cosh(a: Float): Float = nativeMath.cosh(a.toDouble()).toFloat(
  * Computes the hyperbolic tangent of the value [a].
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(+Inf)` is `1.0`
  *   - `tanh(-Inf)` is `-1.0`
@@ -755,7 +742,6 @@ public inline fun tanh(a: Float): Float = nativeMath.tanh(a.toDouble()).toFloat(
  * The returned value is `x` such that `sinh(x) == a`.
  *
  * Special cases:
- *
  *   - `asinh(NaN)` is `NaN`
  *   - `asinh(+Inf)` is `+Inf`
  *   - `asinh(-Inf)` is `-Inf`
@@ -770,7 +756,6 @@ public inline fun asinh(a: Float): Float = asinh(a.toDouble()).toFloat()
  * The returned value is positive `x` such that `cosh(x) == a`.
  *
  * Special cases:
- *
  *   - `acosh(NaN)` is `NaN`
  *   - `acosh(x)` is `NaN` when `x < 1`
  *   - `acosh(+Inf)` is `+Inf`
@@ -785,7 +770,6 @@ public inline fun acosh(a: Float): Float = acosh(a.toDouble()).toFloat()
  * The returned value is `x` such that `tanh(x) == a`.
  *
  * Special cases:
- *
  *   - `tanh(NaN)` is `NaN`
  *   - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
  *   - `tanh(1.0)` is `+Inf`
@@ -853,6 +837,8 @@ public inline fun expm1(a: Float): Float = nativeMath.expm1(a.toDouble()).toFloa
  *   - `log(+Inf, +Inf)` is `NaN`
  *   - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
  *   - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
+ *
+ * See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
  */
 @SinceKotlin("1.2")
 public fun log(a: Float, base: Float): Float {