[stdlib] Improve docs for FP comparison predicates

Author: natecook1000

stdlib/public/core/FloatingPoint.swift.gyb

@@ -1038,7 +1038,8 @@ public protocol FloatingPoint: SignedNumeric, Strideable, Hashable {
  ///
  /// - Parameter other: The value to compare with this value.
  /// - Returns: `true` if `other` has the same value as this instance;
- /// otherwise, `false`.
+ /// otherwise, `false`. If either this value or `other` is NaN, the result
+ /// of this method is `false`.
  func isEqual(to other: Self) -> Bool
 
  /// Returns a Boolean value indicating whether this instance is less than the
@@ -1068,7 +1069,9 @@ public protocol FloatingPoint: SignedNumeric, Strideable, Hashable {
  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
  ///
  /// - Parameter other: The value to compare with this value.
- /// - Returns: `true` if `other` is less than this value; otherwise, `false`.
+ /// - Returns: `true` if this value is less than `other`; otherwise, `false`.
+ /// If either this value or `other` is NaN, the result of this method is
+ /// `false`.
  func isLess(than other: Self) -> Bool
 
  /// Returns a Boolean value indicating whether this instance is less than or
@@ -1096,33 +1099,33 @@ public protocol FloatingPoint: SignedNumeric, Strideable, Hashable {
  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
  ///
  /// - Parameter other: The value to compare with this value.
- /// - Returns: `true` if `other` is less than this value; otherwise, `false`.
+ /// - Returns: `true` if `other` is greater than this value; otherwise,
+ /// `false`. If either this value or `other` is NaN, the result of this
+ /// method is `false`.
  func isLessThanOrEqualTo(_ other: Self) -> Bool
 
- /// Returns a Boolean value indicating whether this instance should precede the
- /// given value in an ascending sort.
+ /// Returns a Boolean value indicating whether this instance should precede
+ /// or tie positions with the given value in an ascending sort.
  ///
  /// This relation is a refinement of the less-than-or-equal-to operator
  /// (`<=`) that provides a total order on all values of the type, including
- /// noncanonical encodings, signed zeros, and NaNs. Because it is used much
- /// less frequently than the usual comparisons, there is no operator form of
- /// this relation.
+ /// signed zeros and NaNs.
  ///
- /// The following example uses `isTotallyOrdered(below:)` to sort an array of
- /// floating-point values, including some that are NaN:
+ /// The following example uses `isTotallyOrdered(belowOrEqualTo:)` to sort an
+ /// array of floating-point values, including some that are NaN:
  ///
  /// var numbers = [2.5, 21.25, 3.0, .nan, -9.5]
- /// numbers.sort { $0.isTotallyOrdered(below: $1) }
- /// // numbers == [-9.5, 2.5, 3.0, 21.25, nan]
+ /// numbers.sort { !$1.isTotallyOrdered(belowOrEqualTo: $0) }
+ /// // numbers == [-9.5, 2.5, 3.0, 21.25, NaN]
  ///
  /// The `isTotallyOrdered(belowOrEqualTo:)` method implements the total order
  /// relation as defined by the [IEEE 754 specification][spec].
  ///
  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
  ///
  /// - Parameter other: A floating-point value to compare to this value.
- /// - Returns: `true` if this value is ordered below `other` in a total
- /// ordering of the floating-point type; otherwise, `false`.
+ /// - Returns: `true` if this value is ordered below or the same as `other`
+ /// in a total ordering of the floating-point type; otherwise, `false`.
  func isTotallyOrdered(belowOrEqualTo other: Self) -> Bool
 
  /// A Boolean value indicating whether this instance is normal.
@@ -2029,30 +2032,28 @@ extension BinaryFloatingPoint {
  significandBitPattern: magnitudeOf.significandBitPattern)
  }
 
- /// Returns a Boolean value indicating whether this instance should precede the
- /// given value in an ascending sort.
+ /// Returns a Boolean value indicating whether this instance should precede
+ /// or tie positions with the given value in an ascending sort.
  ///
  /// This relation is a refinement of the less-than-or-equal-to operator
  /// (`<=`) that provides a total order on all values of the type, including
- /// noncanonical encodings, signed zeros, and NaNs. Because it is used much
- /// less frequently than the usual comparisons, there is no operator form of
- /// this relation.
+ /// signed zeros and NaNs.
  ///
- /// The following example uses `isTotallyOrdered(below:)` to sort an array of
- /// floating-point values, including some that are NaN:
+ /// The following example uses `isTotallyOrdered(belowOrEqualTo:)` to sort an
+ /// array of floating-point values, including some that are NaN:
  ///
  /// var numbers = [2.5, 21.25, 3.0, .nan, -9.5]
- /// numbers.sort { $0.isTotallyOrdered(below: $1) }
- /// // numbers == [-9.5, 2.5, 3.0, 21.25, nan]
+ /// numbers.sort { !$1.isTotallyOrdered(belowOrEqualTo: $0) }
+ /// // numbers == [-9.5, 2.5, 3.0, 21.25, NaN]
  ///
  /// The `isTotallyOrdered(belowOrEqualTo:)` method implements the total order
  /// relation as defined by the [IEEE 754 specification][spec].
  ///
  /// [spec]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933
  ///
  /// - Parameter other: A floating-point value to compare to this value.
- /// - Returns: `true` if this value is ordered below `other` in a total
- /// ordering of the floating-point type; otherwise, `false`.
+ /// - Returns: `true` if this value is ordered below or the same as `other`
+ /// in a total ordering of the floating-point type; otherwise, `false`.
  public func isTotallyOrdered(belowOrEqualTo other: Self) -> Bool {
  // Quick return when possible.
  if self < other { return true }