 //===----------------------------------------------------------------------===//
 
 extension Numeric where Magnitude: FloatingPoint {
-  /// Compares `self` and `other` for approximate equality with default
-  /// tolerances.
+  /// Compares `self` and `other` for approximate equality with a specified
+  /// relative tolerance and implicit absolute tolerance.
   ///
-  /// `a.isApproximatelyEqual(to: b)` is `true` if `a` and `b`
-  /// are equal, or if both are finite and `|a - b| ≤ √u * max(|a|,|b|,n)`,
-  /// where `||` is the norm computed by the `.magnitude` property,
-  /// `u` is `.ulpOfOne`, and `n` is `.leastNormalMagnitude`.
+  /// `true` if `self` and `other` are equal, or if they are finite and
+  /// ```
+  /// (self - other).magnitude ≤ relativeTolerance * scale
+  /// ```
+  /// where `scale` is
+  /// ```
+  /// max(self.magnitude, other.magnitude, .leastNormalMagnitude)
+  /// ```
   ///
-  /// Due to rounding of intermediate results, "the same" value computed using
-  /// two different techniques frequently has slightly different results in
-  /// floating-point arithmetic. This comparison method may be helpful in
-  /// these situations.
-  ///
-  /// ```
-  /// a.isApproximatelyEqual(to: b)
-  /// ```
-  /// is true if `a ` and `b` agree to about half the representable
-  /// significant digits, which is the usual naive guidance in numerical
-  /// analysis ("if you don't have a careful analysis, half your bits
-  /// are probably bad").
-  ///
-  /// More precisely, the call shown above is exactly equivalent to:
-  /// ```
-  /// let rtol = Magnitude.ulpOfOne.squareRoot()
-  /// a.isApproximatelyEqual(to: b, relativeTolerance: rtol)
-  /// ```
-  /// or:
-  /// ```
-  /// let rtol = Magnitude.ulpOfOne.squareRoot()
-  /// let atol = Magnitude.leastNormalMagnitude * rtol
-  /// a.isApproximatelyEqual(to: b,
-  ///   relativeTolerance: rtol,
-  ///   absoluteTolerance: atol
-  /// )
-  /// ```
-  /// Consult the documentation for those methods for a detailed
-  /// description of how the comparison is performed, and how to
-  /// choose tolerances for your particular situation.
+  /// The default value of `relativeTolerance` is `.ulpOfOne.squareRoot()`,
+  /// which corresponds to expecting "about half the digits" in the computed results to be good.
+  /// This is the usual guidance in numerical analysis, if you don't know anything about the
+  /// computation being performed, but is not suitable for all use cases.
   ///
   /// Mathematical Properties:
   /// -

      "but is \(relativeTolerance)."
    )
    if self == other { return true }
    let delta = (self - other).magnitude
    let scale = max(self.magnitude, other.magnitude)
    let bound = max(absoluteTolerance, scale*relativeTolerance)
    return delta.isFinite && delta <= bound
  }

  ///   (Under the assumption that the `.magnitude` property implements a valid norm.)
  ///
  /// - `isApproximatelyEqual(to:relativeTolerance:)` is _scale invariant_,
  ///   so long as no underflow or overflow has occured, and no exceptional value is produced
  ///   by the scaling.
  ///
  /// - Parameters:
  ///   - other: The value to which `self` is compared.
  ///   - relativeTolerance: The tolerance to use for the comparison.
  ///   If no tolerance is provided, `.ulpOfOne.squareRoot()` is used.
  ///   This value should be non-negative and less than or equal to 1.
  ///   This constraint on is only checked in debug builds, because a mathematically
  ///   well-defined result exists for any tolerance, even one out of range.
  @inlinable @inline(__always)
  public func isApproximatelyEqual(
    to other: Self,
    relativeTolerance: Magnitude = Magnitude.ulpOfOne.squareRoot()
  ) -> Bool {
    return isApproximatelyEqual(
      to: other,
      absoluteTolerance: relativeTolerance * Magnitude.leastNormalMagnitude,
      relativeTolerance: relativeTolerance
    )
  }
  
  /// Compares `self` and `other` for approximate equality with a specified tolerances.
  ///
  /// `true` if `self` and `other` are equal, or if they are finite and either
  /// ```
  /// (self - other).magnitude ≤ absoluteTolerance
  /// ```
  /// or
  /// ```
  /// (self - other).magnitude ≤ relativeTolerance * scale
  /// ```
  /// where `scale` is `max(self.magnitude, other.magnitude)`.
  ///
  /// Mathematical Properties:
  /// -
  /// - `isApproximatelyEqual(to:absoluteTolerance:relativeTolerance:)`
  ///   is _reflexive_ for non-exceptional values (such as NaN).
  ///
  /// - `isApproximatelyEqual(to:absoluteTolerance:relativeTolerance:)`
  ///   is _symmetric_.
  ///
  /// - `isApproximatelyEqual(to:absoluteTolerance:relativeTolerance:)`
  ///   is __not__ _transitive_. Because of this, approximately equality is
  ///   __not an equivalence relation__, even when restricted to non-exceptional values.
  ///
  /// - For any point `a`, the set of values that compare approximately equal to `a` is _convex_.
  ///   (Under the assumption that `norm` implements a valid norm, which cannot be checked
  ///   by this function.)
  ///
  /// - Parameters:
  ///   - other: The value to which `self` is compared.
  ///   - absoluteTolerance: The absolute tolerance to use in the comparison.
  ///   This value should be non-negative and finite.
  ///   This constraint on is only checked in debug builds, because a mathematically
  ///   well-defined result exists for any tolerance, even one out of range.
  ///   - relativeTolerance: The relative tolerance to use in the comparison.
  ///   If no relativeTolerance is provided, zero is used.
  ///   This value should be non-negative and less than or equal to 1.
  ///   This constraint on is only checked in debug builds, because a mathematically
  ///   well-defined result exists for any tolerance, even one out of range.
  ///   - norm: Allows you to specify what norm to use. Defaults to using the
  ///   `.magnitude` property.
  @inlinable @inline(__always)
  public func isApproximatelyEqual(
    to other: Self,
    absoluteTolerance: Magnitude,
    relativeTolerance: Magnitude = 0,
    norm: (Self) -> Magnitude = { $0.magnitude }
  ) -> Bool {
    assert(
      absoluteTolerance >= 0 && absoluteTolerance.isFinite,
