diff --git a/libraries/stdlib/src/kotlin/comparisons/Comparisons.kt b/libraries/stdlib/src/kotlin/comparisons/Comparisons.kt index bdbe59aac0e..5e4f538e8d0 100644 --- a/libraries/stdlib/src/kotlin/comparisons/Comparisons.kt +++ b/libraries/stdlib/src/kotlin/comparisons/Comparisons.kt @@ -1,5 +1,5 @@ /* - * Copyright 2010-2018 JetBrains s.r.o. and Kotlin Programming Language contributors. + * Copyright 2010-2022 JetBrains s.r.o. and Kotlin Programming Language contributors. * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file. */ @file:kotlin.jvm.JvmName("ComparisonsKt") @@ -225,6 +225,7 @@ public infix fun Comparator.thenDescending(comparator: Comparator): /** * Extends the given [comparator] of non-nullable values to a comparator of nullable values * considering `null` value less than any other value. + * Non-null values are compared with the provided [comparator]. * * @sample samples.comparisons.Comparisons.nullsFirstLastWithComparator */ @@ -241,6 +242,7 @@ public fun nullsFirst(comparator: Comparator): Comparator = /** * Provides a comparator of nullable [Comparable] values * considering `null` value less than any other value. + * Non-null values are compared according to their [natural order][naturalOrder]. * * @sample samples.comparisons.Comparisons.nullsFirstLastComparator */ @@ -250,6 +252,7 @@ public inline fun > nullsFirst(): Comparator = nullsFirst( /** * Extends the given [comparator] of non-nullable values to a comparator of nullable values * considering `null` value greater than any other value. + * Non-null values are compared with the provided [comparator]. * * @sample samples.comparisons.Comparisons.nullsFirstLastWithComparator */ @@ -266,6 +269,7 @@ public fun nullsLast(comparator: Comparator): Comparator = /** * Provides a comparator of nullable [Comparable] values * considering `null` value greater than any other value. + * Non-null values are compared according to their [natural order][naturalOrder]. * * @sample samples.comparisons.Comparisons.nullsFirstLastComparator */ @@ -275,6 +279,8 @@ public inline fun > nullsLast(): Comparator = nullsLast(na /** * Returns a comparator that compares [Comparable] objects in natural order. * + * The natural order of a `Comparable` type here means the order established by its `compareTo` function. + * * @sample samples.comparisons.Comparisons.naturalOrderComparator */ public fun > naturalOrder(): Comparator = @Suppress("UNCHECKED_CAST") (NaturalOrderComparator as Comparator) @@ -282,6 +288,8 @@ public fun > naturalOrder(): Comparator = @Suppress("UNCHEC /** * Returns a comparator that compares [Comparable] objects in reversed natural order. * + * The natural order of a `Comparable` type here means the order established by its `compareTo` function. + * * @sample samples.comparisons.Comparisons.nullsFirstLastWithComparator */ public fun > reverseOrder(): Comparator = @Suppress("UNCHECKED_CAST") (ReverseOrderComparator as Comparator)