From 3bf38e62c8f0e397489a70c71da7e0e1979c8c6a Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Mon, 9 Jan 2017 23:53:21 +0300
Subject: [PATCH] Add a note about NaN propagation for floating point
 specializations.

---
 js/js.libraries/src/core/generated/_ArraysJs.kt  | 16 ++++++++++++++++
 .../src/core/generated/_CollectionsJs.kt         |  8 ++++++++
 .../src/core/generated/_SequencesJs.kt           |  8 ++++++++
 libraries/stdlib/common/src/generated/_Arrays.kt | 16 ++++++++++++++++
 .../stdlib/common/src/generated/_Collections.kt  |  8 ++++++++
 .../stdlib/common/src/generated/_Sequences.kt    |  8 ++++++++
 libraries/stdlib/src/generated/_Arrays.kt        | 16 ++++++++++++++++
 libraries/stdlib/src/generated/_Collections.kt   |  8 ++++++++
 libraries/stdlib/src/generated/_Sequences.kt     |  8 ++++++++
 .../src/templates/Aggregates.kt                  |  5 ++++-
 .../src/templates/Comparables.kt                 |  4 ++++
 11 files changed, 104 insertions(+), 1 deletion(-)

diff --git a/js/js.libraries/src/core/generated/_ArraysJs.kt b/js/js.libraries/src/core/generated/_ArraysJs.kt
index eeccf2de9a6..da8756c4b7d 100644
--- a/js/js.libraries/src/core/generated/_ArraysJs.kt
+++ b/js/js.libraries/src/core/generated/_ArraysJs.kt
@@ -9722,6 +9722,8 @@ public inline fun CharArray.forEachIndexed(action: (Int, Char) -> Unit): Unit {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Array<out Double>.max(): Double? {
@@ -9738,6 +9740,8 @@ public fun Array<out Double>.max(): Double? {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Array<out Float>.max(): Float? {
@@ -9819,6 +9823,8 @@ public fun LongArray.max(): Long? {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public fun FloatArray.max(): Float? {
     if (isEmpty()) return null
@@ -9834,6 +9840,8 @@ public fun FloatArray.max(): Float? {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public fun DoubleArray.max(): Double? {
     if (isEmpty()) return null
@@ -10141,6 +10149,8 @@ public fun CharArray.maxWith(comparator: Comparator<in Char>): Char? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Array<out Double>.min(): Double? {
@@ -10157,6 +10167,8 @@ public fun Array<out Double>.min(): Double? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Array<out Float>.min(): Float? {
@@ -10238,6 +10250,8 @@ public fun LongArray.min(): Long? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public fun FloatArray.min(): Float? {
     if (isEmpty()) return null
@@ -10253,6 +10267,8 @@ public fun FloatArray.min(): Float? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public fun DoubleArray.min(): Double? {
     if (isEmpty()) return null
diff --git a/js/js.libraries/src/core/generated/_CollectionsJs.kt b/js/js.libraries/src/core/generated/_CollectionsJs.kt
index 538cd6f4abd..a374a628647 100644
--- a/js/js.libraries/src/core/generated/_CollectionsJs.kt
+++ b/js/js.libraries/src/core/generated/_CollectionsJs.kt
@@ -1464,6 +1464,8 @@ public inline fun <T> Iterable<T>.forEachIndexed(action: (Int, T) -> Unit): Unit
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Iterable<Double>.max(): Double? {
@@ -1481,6 +1483,8 @@ public fun Iterable<Double>.max(): Double? {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Iterable<Float>.max(): Float? {
@@ -1545,6 +1549,8 @@ public fun <T> Iterable<T>.maxWith(comparator: Comparator<in T>): T? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Iterable<Double>.min(): Double? {
@@ -1562,6 +1568,8 @@ public fun Iterable<Double>.min(): Double? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Iterable<Float>.min(): Float? {
diff --git a/js/js.libraries/src/core/generated/_SequencesJs.kt b/js/js.libraries/src/core/generated/_SequencesJs.kt
index a12ef08a191..2f84d64589a 100644
--- a/js/js.libraries/src/core/generated/_SequencesJs.kt
+++ b/js/js.libraries/src/core/generated/_SequencesJs.kt
@@ -843,6 +843,8 @@ public inline fun <T> Sequence<T>.forEachIndexed(action: (Int, T) -> Unit): Unit
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Sequence<Double>.max(): Double? {
@@ -860,6 +862,8 @@ public fun Sequence<Double>.max(): Double? {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Sequence<Float>.max(): Float? {
@@ -924,6 +928,8 @@ public fun <T> Sequence<T>.maxWith(comparator: Comparator<in T>): T? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Sequence<Double>.min(): Double? {
@@ -941,6 +947,8 @@ public fun Sequence<Double>.min(): Double? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Sequence<Float>.min(): Float? {
diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt
index 312a52928eb..62d6d259024 100644
--- a/libraries/stdlib/common/src/generated/_Arrays.kt
+++ b/libraries/stdlib/common/src/generated/_Arrays.kt
@@ -5753,12 +5753,16 @@ public header inline fun CharArray.forEachIndexed(action: (Int, Char) -> Unit):
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Array<out Double>.max(): Double?
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Array<out Float>.max(): Float?
@@ -5790,11 +5794,15 @@ public header fun LongArray.max(): Long?
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public header fun FloatArray.max(): Float?
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public header fun DoubleArray.max(): Double?
 
@@ -5895,12 +5903,16 @@ public header fun CharArray.maxWith(comparator: Comparator<in Char>): Char?
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Array<out Double>.min(): Double?
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Array<out Float>.min(): Float?
@@ -5932,11 +5944,15 @@ public header fun LongArray.min(): Long?
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public header fun FloatArray.min(): Float?
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public header fun DoubleArray.min(): Double?
 
diff --git a/libraries/stdlib/common/src/generated/_Collections.kt b/libraries/stdlib/common/src/generated/_Collections.kt
index 5f6ef05850b..3f2b557d262 100644
--- a/libraries/stdlib/common/src/generated/_Collections.kt
+++ b/libraries/stdlib/common/src/generated/_Collections.kt
@@ -767,12 +767,16 @@ public header inline fun <T> Iterable<T>.forEachIndexed(action: (Int, T) -> Unit
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Iterable<Double>.max(): Double?
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Iterable<Float>.max(): Float?
@@ -794,12 +798,16 @@ public header fun <T> Iterable<T>.maxWith(comparator: Comparator<in T>): T?
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Iterable<Double>.min(): Double?
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Iterable<Float>.min(): Float?
diff --git a/libraries/stdlib/common/src/generated/_Sequences.kt b/libraries/stdlib/common/src/generated/_Sequences.kt
index ccfe14fd14b..db6a478f0ab 100644
--- a/libraries/stdlib/common/src/generated/_Sequences.kt
+++ b/libraries/stdlib/common/src/generated/_Sequences.kt
@@ -494,12 +494,16 @@ public header inline fun <T> Sequence<T>.forEachIndexed(action: (Int, T) -> Unit
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Sequence<Double>.max(): Double?
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Sequence<Float>.max(): Float?
@@ -521,12 +525,16 @@ public header fun <T> Sequence<T>.maxWith(comparator: Comparator<in T>): T?
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Sequence<Double>.min(): Double?
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public header fun Sequence<Float>.min(): Float?
diff --git a/libraries/stdlib/src/generated/_Arrays.kt b/libraries/stdlib/src/generated/_Arrays.kt
index 8c7c316aca8..cf5b026aad7 100644
--- a/libraries/stdlib/src/generated/_Arrays.kt
+++ b/libraries/stdlib/src/generated/_Arrays.kt
@@ -9805,6 +9805,8 @@ public inline fun CharArray.forEachIndexed(action: (Int, Char) -> Unit): Unit {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Array<out Double>.max(): Double? {
@@ -9821,6 +9823,8 @@ public fun Array<out Double>.max(): Double? {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Array<out Float>.max(): Float? {
@@ -9902,6 +9906,8 @@ public fun LongArray.max(): Long? {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public fun FloatArray.max(): Float? {
     if (isEmpty()) return null
@@ -9917,6 +9923,8 @@ public fun FloatArray.max(): Float? {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public fun DoubleArray.max(): Double? {
     if (isEmpty()) return null
@@ -10224,6 +10232,8 @@ public fun CharArray.maxWith(comparator: Comparator<in Char>): Char? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Array<out Double>.min(): Double? {
@@ -10240,6 +10250,8 @@ public fun Array<out Double>.min(): Double? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Array<out Float>.min(): Float? {
@@ -10321,6 +10333,8 @@ public fun LongArray.min(): Long? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public fun FloatArray.min(): Float? {
     if (isEmpty()) return null
@@ -10336,6 +10350,8 @@ public fun FloatArray.min(): Float? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 public fun DoubleArray.min(): Double? {
     if (isEmpty()) return null
diff --git a/libraries/stdlib/src/generated/_Collections.kt b/libraries/stdlib/src/generated/_Collections.kt
index cf570779215..3eed5f12eaa 100644
--- a/libraries/stdlib/src/generated/_Collections.kt
+++ b/libraries/stdlib/src/generated/_Collections.kt
@@ -1475,6 +1475,8 @@ public inline fun <T> Iterable<T>.forEachIndexed(action: (Int, T) -> Unit): Unit
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Iterable<Double>.max(): Double? {
@@ -1492,6 +1494,8 @@ public fun Iterable<Double>.max(): Double? {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Iterable<Float>.max(): Float? {
@@ -1556,6 +1560,8 @@ public fun <T> Iterable<T>.maxWith(comparator: Comparator<in T>): T? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Iterable<Double>.min(): Double? {
@@ -1573,6 +1579,8 @@ public fun Iterable<Double>.min(): Double? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Iterable<Float>.min(): Float? {
diff --git a/libraries/stdlib/src/generated/_Sequences.kt b/libraries/stdlib/src/generated/_Sequences.kt
index dfb391e6ddf..0439366c14d 100644
--- a/libraries/stdlib/src/generated/_Sequences.kt
+++ b/libraries/stdlib/src/generated/_Sequences.kt
@@ -862,6 +862,8 @@ public inline fun <T> Sequence<T>.forEachIndexed(action: (Int, T) -> Unit): Unit
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Sequence<Double>.max(): Double? {
@@ -879,6 +881,8 @@ public fun Sequence<Double>.max(): Double? {
 
 /**
  * Returns the largest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Sequence<Float>.max(): Float? {
@@ -943,6 +947,8 @@ public fun <T> Sequence<T>.maxWith(comparator: Comparator<in T>): T? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Sequence<Double>.min(): Double? {
@@ -960,6 +966,8 @@ public fun Sequence<Double>.min(): Double? {
 
 /**
  * Returns the smallest element or `null` if there are no elements.
+ * 
+ * If any of elements is `NaN` returns `NaN`.
  */
 @SinceKotlin("1.1")
 public fun Sequence<Float>.min(): Float? {
diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt
index 2a431b1646a..a9f49dde9d6 100644
--- a/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt
+++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt
@@ -159,7 +159,10 @@ fun aggregates(): List<GenericFunction> {
                     if (isFloat && isGeneric)
                         since("1.1")
                 }
-                doc { f -> "Returns the ${if (op == "max") "largest" else "smallest"} ${f.element} or `null` if there are no ${f.element.pluralize()}." }
+                doc { f ->
+                    "Returns the ${if (op == "max") "largest" else "smallest"} ${f.element} or `null` if there are no ${f.element.pluralize()}." +
+                    if (isFloat) "\n\n" + "If any of ${f.element.pluralize()} is `NaN` returns `NaN`."  else ""
+                }
                 returns("T?")
 
                 body {
diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt
index 41d367f616e..37232496026 100644
--- a/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt
+++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt
@@ -130,6 +130,7 @@ fun comparables(): List<GenericFunction> {
             If values are equal, returns the first one.
             """
         }
+        // TODO: Add a note about NaN propagation for floats.
         doc(Primitives) {
             """Returns the smaller of two values."""
         }
@@ -154,6 +155,7 @@ fun comparables(): List<GenericFunction> {
         returns("T")
         customReceiver("")
         inline(Primitives) { Inline.Only }
+        // TODO: Add a note about NaN propagation for floats.
         doc {
             """
             Returns the smaller of three values.
@@ -215,6 +217,7 @@ fun comparables(): List<GenericFunction> {
             If values are equal, returns the first one.
             """
         }
+        // TODO: Add a note about NaN propagation for floats.
         doc(Primitives) {
             """Returns the greater of two values."""
         }
@@ -238,6 +241,7 @@ fun comparables(): List<GenericFunction> {
         returns("T")
         customReceiver("")
         inline(Primitives) { Inline.Only }
+        // TODO: Add a note about NaN propagation for floats.
         doc {
             """
             Returns the greater of three values.