80-column formatting for source doc comments

Tidying, plus a few small edits. This commit should not include any code changes.

Author: stephentyrone

Sources/ComplexModule/Arithmetic.swift

@@ -126,8 +126,8 @@ extension Complex: AlgebraicField {
 
   /// A normalized complex number with the same phase as this value.
   ///
-  /// If such a value cannot be produced (because the phase of zero and infinity is undefined),
-  /// `nil` is returned.
+  /// If such a value cannot be produced (because the phase of zero and
+  /// infinity is undefined), `nil` is returned.
   @inlinable
   public var normalized: Complex? {
     if length.isNormal {
@@ -139,10 +139,12 @@ extension Complex: AlgebraicField {
     return self.divided(by: magnitude).normalized
   }
 
-  /// The reciprocal of this value, if it can be computed without undue overflow or underflow.
+  /// The reciprocal of this value, if it can be computed without undue
+  /// overflow or underflow.
   ///
-  /// If z.reciprocal is non-nil, you can safely replace division by z with multiplication by this value. It is
-  /// not advantageous to do this for an isolated division, but if you are dividing many values by a single
+  /// If z.reciprocal is non-nil, you can safely replace division by z with
+  /// multiplication by this value. It is not advantageous to do this for an
+  /// isolated division, but if you are dividing many values by a single
   /// denominator, this will often be a significant performance win.
   ///
   /// Typical use looks like this:

Sources/ComplexModule/Complex.swift

@@ -163,9 +163,10 @@ extension Complex {
 
   /// True if this value is normal.
   ///
-  /// A complex number is normal if it is finite and *either* the real or imaginary component is normal.
-  /// A floating-point number representing one of the components is normal if its exponent allows a full-
-  /// precision representation.
+  /// A complex number is normal if it is finite and *either* the real or
+  /// imaginary component is normal. A floating-point number representing
+  /// one of the components is normal if its exponent allows a full-precision
+  /// representation.
   ///
   /// See also:
   /// -
@@ -179,9 +180,10 @@ extension Complex {
 
   /// True if this value is subnormal.
   ///
-  /// A complex number is subnormal if it is finite, not normal, and not zero. When the result of a
-  /// computation is subnormal, underflow has occurred and the result generally does not have full
-  /// precision.
+  /// A complex number is subnormal if it is finite, not normal, and not zero.
+  /// When the result of a computation is subnormal, underflow has occurred and
+  /// the result generally does not have full precision.
+  ///
   /// See also:
   /// -
   /// - `.isFinite`
@@ -194,7 +196,8 @@ extension Complex {
 
   /// True if this value is zero.
   ///
-  /// A complex number is zero if *both* the real and imaginary components are zero.
+  /// A complex number is zero if *both* the real and imaginary components
+  /// are zero.
   ///
   /// See also:
   /// -
@@ -208,8 +211,8 @@ extension Complex {
 
   /// The ∞-norm of the value (`max(abs(real), abs(imaginary))`).
   ///
-  /// If you need the Euclidean norm (a.k.a. 2-norm) use the `length` or `lengthSquared`
-  /// properties instead.
+  /// If you need the Euclidean norm (a.k.a. 2-norm) use the `length` or
+  /// `lengthSquared` properties instead.
   ///
   /// Edge cases:
   /// -
@@ -240,8 +243,8 @@ extension Complex {
   /// This is mainly useful for interoperation with other languages, where
   /// you may want to reduce each equivalence class to a single representative
   /// before passing across language boundaries, but it may also be useful
-  /// for some serialization tasks. It's also a useful implementation detail for
-  /// some primitive operations.
+  /// for some serialization tasks. It's also a useful implementation detail
+  /// for some primitive operations.
   @_transparent
   public var canonicalized: Self {
     if isZero { return .zero }
@@ -491,7 +494,8 @@ extension Complex {
   ///
   /// Edge cases:
   /// -
-  /// - Negative lengths are interpreted as reflecting the point through the origin, i.e.:
+  /// - Negative lengths are interpreted as reflecting the point through the
+  ///   origin, i.e.:
   ///   ```
   ///   Complex(length: -r, phase: θ) == -Complex(length: r, phase: θ)
   ///   ```

Sources/ComplexModule/ElementaryFunctions.swift

@@ -39,17 +39,19 @@ extension Complex: ElementaryFunctions {
 
   // MARK: - exp-like functions
 
-  /// The complex exponential function e^z whose base `e` is the base of the natural logarithm.
+  /// The complex exponential function e^z whose base `e` is the base of the
+  /// natural logarithm.
   ///
-  /// Mathematically, this operation can be expanded in terms of the `Real` operations `exp`,
-  /// `cos` and `sin` as follows:
+  /// Mathematically, this operation can be expanded in terms of the `Real`
+  /// operations `exp`, `cos` and `sin` as follows:
   /// ```
   /// exp(x + iy) = exp(x) exp(iy)
   ///             = exp(x) cos(y) + i exp(x) sin(y)
   /// ```
-  /// Note that naive evaluation of this expression in floating-point would be prone to premature
-  /// overflow, since `cos` and `sin` both have magnitude less than 1 for most inputs (i.e.
-  /// `exp(x)` may be infinity when `exp(x) cos(y)` would not be.
+  /// Note that naive evaluation of this expression in floating-point would be
+  /// prone to premature overflow, since `cos` and `sin` both have magnitude
+  /// less than 1 for most inputs (i.e. `exp(x)` may be infinity when
+  /// `exp(x) cos(y)` would not be).
   @inlinable
   public static func exp(_ z: Complex) -> Complex {
     guard z.isFinite else { return z }

Sources/RealModule/ApproximateEquality.swift

@@ -22,9 +22,10 @@ extension Numeric where Magnitude: FloatingPoint {
   /// ```
   ///
   /// 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.
+  /// 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:
   /// ------------------------
@@ -34,16 +35,21 @@ extension Numeric where Magnitude: FloatingPoint {
   ///
   /// - `isApproximatelyEqual(to:relativeTolerance:norm:)` is _symmetric_.
   ///
-  /// - `isApproximatelyEqual(to:relativeTolerance:norm:)` is __not__ _transitive_.
-  ///   Because of this, approximately equality is __not an equivalence relation__,
-  ///   even when restricted to non-exceptional values.
+  /// - `isApproximatelyEqual(to:relativeTolerance:norm:)` 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 the `.magnitude` property implements a valid norm.)
+  ///   This means that you must not use approximate equality to implement
+  ///   a conformance to Equatable, as it will violate the invariants of
+  ///   code written against that protocol.
+  ///
+  /// - For any point `a`, the set of values that compare approximately equal
+  ///   to `a` is _convex_. (Under the assumption that the `.magnitude`
+  ///   property implements a valid norm.)
   ///
   /// - `isApproximatelyEqual(to:relativeTolerance:norm:)` is _scale invariant_,
-  ///   so long as no underflow or overflow has occured, and no exceptional value is produced
-  ///   by the scaling.
+  ///   so long as no underflow or overflow has occured, and no exceptional
+  ///   value is produced by the scaling.
   ///
   /// See Also:
   /// -------
@@ -57,8 +63,9 @@ extension Numeric where Magnitude: FloatingPoint {
   ///     Defaults to `.ulpOfOne.squareRoot()`.
   ///
   ///     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.
+  ///     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: The [norm] to use for the comparison.
   ///     Defaults to `\.magnitude`.
@@ -99,13 +106,17 @@ extension Numeric where Magnitude: FloatingPoint {
   /// - `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.
+  /// - `isApproximatelyEqual(to:relativeTolerance:norm:)` 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.)
+  ///   This means that you must not use approximate equality to implement
+  ///   a conformance to Equatable, as it will violate the invariants of
+  ///   code written against that protocol.
+  ///
+  /// - 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.)
   ///
   /// See Also:
   /// -------
@@ -118,15 +129,17 @@ extension Numeric where Magnitude: FloatingPoint {
   ///   - 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.
+  ///     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.
   ///     Defaults to zero.
   ///
   ///     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.
+  ///     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,
@@ -143,7 +156,8 @@ extension Numeric where Magnitude: FloatingPoint {
 }
 
 extension AdditiveArithmetic {
-  /// Test if `self` and `other` are approximately equal with specified tolerances and norm.
+  /// Test if `self` and `other` are approximately equal with specified
+  /// tolerances and norm.
   ///
   /// `true` if `self` and `other` are equal, or if they are finite and either
   /// ```
@@ -166,11 +180,16 @@ extension AdditiveArithmetic {
   ///
   /// - `isApproximatelyEqual(to:absoluteTolerance:relativeTolerance:norm:)`
   ///   is __not__ _transitive_. Because of this, approximately equality is
-  ///   __not an equivalence relation__, even when restricted to non-exceptional values.
+  ///   __not an equivalence relation__, even when restricted to
+  ///   non-exceptional values.
+  ///
+  ///   This means that you must not use approximate equality to implement
+  ///   a conformance to Equatable, as it will violate the invariants of
+  ///   code written against that protocol.
   ///
-  /// - 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.)
+  /// - 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 or a protocol).
   ///
   /// See Also:
   /// -------
@@ -184,30 +203,32 @@ extension AdditiveArithmetic {
   ///   - 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.
+  ///     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.
   ///     Defaults to zero.
   ///
   ///     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.
+  ///     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: The norm to use for the comparison.
   ///     Defaults to `\.magnitude`.
   ///
-  ///     For example, if we wanted to test if a complex value was inside a circle of
-  ///     radius 0.001 centered at (1 + 0i), we could use:
+  ///     For example, if we wanted to test if a complex value was inside a
+  ///     circle of radius 0.001 centered at (1 + 0i), we could use:
   ///     ```
   ///     z.isApproximatelyEqual(
   ///       to: 1,
   ///       absoluteTolerance: 0.001,
   ///       norm: \.length
   ///     )
   ///     ```
-  ///     (if we used the default, we would be testing if `z` were inside a square region
-  ///     instead.)
+  ///     (if we used the default norm, `.magnitude`, we would be testing if
+  ///     `z` were inside a square region instead.)
   @inlinable
   public func isApproximatelyEqual<Magnitude>(
     to other: Self,

Sources/RealModule/ElementaryFunctions.swift

@@ -24,18 +24,21 @@
 /// let y = Float.sin(x) // 0.84147096
 /// ```
 ///
-/// There are three broad families of functions defined by `ElementaryFunctions`:
+/// There are three broad families of functions defined by
+/// `ElementaryFunctions`:
 /// - Exponential, trigonometric, and hyperbolic functions:
 ///   `exp`, `expMinusOne`, `cos`, `sin`, `tan`, `cosh`, `sinh`, and `tanh`.
 /// - Logarithmic, inverse trigonometric, and inverse hyperbolic functions:
-///   `log`, `log(onePlus:)`, `acos`, `asin`, `atan`, `acosh`, `asinh`, and `atanh`.
+///   `log`, `log(onePlus:)`, `acos`, `asin`, `atan`, `acosh`, `asinh`, and
+///   `atanh`.
 /// - Power and root functions:
 ///   `pow`, `sqrt`, and `root`.
 ///
 /// `ElementaryFunctions` conformance implies `AdditiveArithmetic`, so addition
 /// and subtraction and the `.zero` property are also available.
 ///
-/// There are two other protocols that you are more likely to want to use directly:
+/// There are two other protocols that you are more likely to want to use
+/// directly:
 ///
 /// `RealFunctions` refines `ElementaryFunctions` and includes
 /// additional functions specific to real number types.
@@ -50,7 +53,8 @@
 ///
 /// [elfn]: http://en.wikipedia.org/wiki/Elementary_function
 public protocol ElementaryFunctions: AdditiveArithmetic {
-  /// The [exponential function][wiki] e^x whose base `e` is the base of the natural logarithm.
+  /// The [exponential function][wiki] e^x whose base `e` is the base of the
+  /// natural logarithm.
   ///
   /// See also:
   /// -
@@ -63,19 +67,20 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
 
   /// exp(x) - 1, computed in such a way as to maintain accuracy for small x.
   ///
-  /// When `x` is close to zero, the expression `.exp(x) - 1` suffers from catastrophic
-  /// cancellation and the result will not have full accuracy. The `.expMinusOne(x)` function gives
-  /// you a means to address this problem.
+  /// When `x` is close to zero, the expression `.exp(x) - 1` suffers from
+  /// catastrophic cancellation and the result will not have full accuracy.
+  /// The `.expMinusOne(x)` function gives you a means to address this problem.
   ///
-  /// As an example, consider the expression `(x + 1)*exp(x) - 1`.  When `x` is smaller
-  /// than `.ulpOfOne`, this expression evaluates to `0.0`, when it should actually round to
-  /// `2*x`. We can get a full-accuracy result by using the following instead:
+  /// As an example, consider the expression `(x + 1)*exp(x) - 1`.  When `x`
+  /// is smaller than `.ulpOfOne`, this expression evaluates to `0.0`, when it
+  /// should actually round to `2*x`. We can get a full-accuracy result by
+  /// using the following instead:
   /// ```
   /// let t = .expMinusOne(x)
   /// return x*(t+1) + t       // x*exp(x) + (exp(x)-1) = (x+1)*exp(x) - 1
   /// ```
-  /// This re-written expression delivers an accurate result for all values of `x`, not just for
-  /// small values.
+  /// This re-written expression delivers an accurate result for all values
+  /// of `x`, not just for small values.
   ///
   /// See also:
   /// -
@@ -238,7 +243,8 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
 
   /// The [arccosine][wiki] (inverse cosine) of `x`.
   ///
-  /// For real types, the result may be interpreted as an angle measured in radians.
+  /// For real types, the result may be interpreted as an angle measured in
+  /// radians.
   /// ```
   /// cos(acos(x)) ≅ x
   /// ```
@@ -253,7 +259,8 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
 
   /// The [arcsine][wiki]  (inverse sine) of `x`.
   ///
-  /// For real types, the result may be interpreted as an angle measured in radians.
+  /// For real types, the result may be interpreted as an angle measured in
+  /// radians.
   /// ```
   /// sin(asin(x)) ≅ x
   /// ```
@@ -268,7 +275,8 @@ public protocol ElementaryFunctions: AdditiveArithmetic {
 
   /// The [arctangent][wiki]  (inverse tangent) of `x`.
   ///
-  /// For real types, the result may be interpreted as an angle measured in radians.
+  /// For real types, the result may be interpreted as an angle measured in
+  /// radians.
   /// ```
   /// tan(atan(x)) ≅ x
   /// ```