More docc changes.

Author: stephentyrone

Sources/ComplexModule/Complex+Numeric.swift

@@ -37,14 +37,18 @@ extension Complex: Numeric {
     self.init(real, 0)
   }
 
-  /// The ∞-norm of the value (`max(abs(real), abs(imaginary))`).
+  /// The infinity-norm of the value (a.k.a. "maximum norm" or "Чебышёв norm").
   ///
-  /// If you need the Euclidean norm (a.k.a. 2-norm) use the `length` or
-  /// `lengthSquared` properties instead.
+  /// Equal to `max(abs(real), abs(imaginary))`.
   ///
-  /// Edge cases:
-  /// - If `z` is not finite, `z.magnitude` is `.infinity`.
-  /// - If `z` is zero, `z.magnitude` is `0`.
+  /// If you need to work with the Euclidean norm (a.k.a. 2-norm) instead,
+  /// use the `length` or `lengthSquared` properties. If you just need to
+  /// know "how big" a number is, use this property.
+  ///
+  /// **Edge cases:**
+  ///
+  /// - If `z` is not finite, `z.magnitude` is infinity.
+  /// - If `z` is zero, `z.magnitude` is zero.
   /// - Otherwise, `z.magnitude` is finite and non-zero.
   ///
   /// See also `.length` and `.lengthSquared`.

Sources/ComplexModule/Documentation.docc/Infinity.md

@@ -14,10 +14,11 @@ the same.
 
 ## Rationale
 
-This decision has some drawbacks,¹ but also some significant advantages.
-In particular, complex multiplication is one of the most common operations with
-a complex type, and one would like to be able to use the usual naive arithmetic
-implementation, consisting of four real multiplications and two real additions:
+This choice has some drawbacks,¹ but also some significant advantages.
+In particular, complex multiplication is the most common operation performed
+with a complex type, and one would like to be able to use the usual naive 
+arithmetic implementation, consisting of four real multiplications and two
+real additions:
 ```
 (a + bi) * (c + di) = (ac - bd) + (ad + bc)i
 ```

Sources/ComplexModule/Polar.swift

@@ -12,7 +12,7 @@
 import RealModule
 
 extension Complex {
-  /// The Euclidean norm (a.k.a. 2-norm, `sqrt(real*real + imaginary*imaginary)`).
+  /// The Euclidean norm (a.k.a. 2-norm).
   ///
   /// This property takes care to avoid spurious over- or underflow in
   /// this computation. For example:
@@ -28,7 +28,7 @@ extension Complex {
   ///
   /// For most use cases, you can use the cheaper `.magnitude`
   /// property (which computes the ∞-norm) instead, which always produces
-  /// a representable result.
+  /// a representable result. See <doc:Magnitude> for more details.
   ///
   /// Edge cases:
   /// - If a complex value is not finite, its `.length` is `infinity`.
@@ -63,25 +63,24 @@ extension Complex {
   /// For many cases, `.magnitude` can be used instead, which is similarly
   /// cheap to compute and always returns a representable value.
   ///
-  /// See also `.length` and `.magnitude`.
+  /// Note that because of how `lengthSquared` is used, it is a primary
+  /// design goal that it be as fast as possible. Therefore, it does not
+  /// normalize infinities, and may return either `.infinity` or `.nan`
+  /// for non-finite values.
+  ///
+  /// See also ``length`` and ``magnitude``.
   @_transparent
   public var lengthSquared: RealType {
     x*x + y*y
   }
 
-  @available(*, unavailable, renamed: "lengthSquared")
-  public var unsafeLengthSquared: RealType { lengthSquared }
-  
   /// The phase (angle, or "argument").
   ///
-  /// Returns the angle (measured above the real axis) in radians. If
+  /// - Returns: The angle (measured above the real axis) in radians. If
   /// the complex value is zero or infinity, the phase is not defined,
   /// and `nan` is returned.
   ///
-  /// Edge cases:
-  /// - If the complex value is zero or non-finite, phase is `nan`.
-  ///
-  /// See also `.length`, `.polar` and `init(r:θ:)`.
+  /// See also ``length``, ``polar`` and ``init(length:phase:)``.
   @inlinable
   public var phase: RealType {
     guard isFinite && !isZero else { return .nan }

Sources/ComplexModule/Scale.swift

@@ -20,35 +20,22 @@
 // what is the type of b? If we don't have a type context, it's ambiguous.
 // If we have a Complex type context, then b will be inferred to have type
 // Complex! Obviously, that doesn't help anyone.
-//
-// TODO: figure out if there's some way to avoid these surprising results
-// and turn these into operators if/when we have it.
-// (https://github.com/apple/swift-numerics/issues/12)
+
 extension Complex {
-  /// `self` scaled by `a`.
-  @usableFromInline @_transparent
-  internal func multiplied(by a: RealType) -> Complex {
-    // This can be viewed in two different ways, which are mathematically
-    // equivalent: either we are computing `self * Complex(a)` (i.e.
-    // converting `a` to be a complex value, and then using the complex
-    // multiplication) or we are using the scalar product of the vector
-    // space structure: `Complex(a*real, a*imaginary)`.
-    //
-    // Although these two interpretations are _mathematically_ equivalent,
-    // they will generate different representations of the point at
-    // infinity in general. For example, suppose `self` is represented by
-    // `(infinity, 0)`. Then `self * Complex(1)` would evaluate as
-    // `(1*infinity - 0*0, 0*infinity + 1*0) = (infinity, nan)`, but
-    // the vector space interpretation produces `(infinity, 0)`. This does
-    // not matter much, because these are two representations of the same
-    // semantic value, but note that one requires four multiplies and two
-    // additions, while the one we use requires only two real multiplications.
+  /// `self` multiplied by the real value `a`.
+  ///
+  /// Equivalent to `self * Complex(a)`, but may be computed more efficiently.
+  @inlinable @inline(__always)
+  public func multiplied(by a: RealType) -> Complex {
     Complex(x*a, y*a)
   }
 
-  /// `self` unscaled by `a`.
-  @usableFromInline @_transparent
-  internal func divided(by a: RealType) -> Complex {
+  /// `self` divided by the real value `a`.
+  ///
+  /// More efficient than `self / Complex(a)`. May not produce exactly the
+  /// same result, but will always be more accurate when they differ.
+  @inlinable @inline(__always)
+  public func divided(by a: RealType) -> Complex {
     // See implementation notes for `multiplied` above.
     Complex(x/a, y/a)
   }

Sources/IntegerUtilities/DivideWithRounding.swift

@@ -12,26 +12,29 @@
 extension BinaryInteger {
   /// `self` divided by `other`, rounding the result according to `rule`.
   ///
-  /// The default rounding rule is `.down`, which _is not the same_ as the
-  /// behavior of the `/` operator from the Swift standard library, but is
-  /// chosen because it generally produces a more useful remainder. In
-  /// particular, when `b` is positive, the remainder is always positive.
-  /// To match the behavior of `/`, use the `.towardZero` rounding mode.
+  /// By default, this function uses ``RoundingRule/down``, which **is not
+  /// the same** as the rounding of the `/` operator from the Swift standard
+  /// library. They agree when the signs of the arguments match, but produce
+  /// different results when the quotient is negative. This behavior is
+  /// chosen because it generally produces a more useful remainder; in
+  /// particular, when the divisor is positive, the remainder is always
+  /// positive. To match the behavior of `/`, use ``RoundingRule/towardZero``.
   ///
   /// Note that the remainder of division is not always representable in an
-  /// unsigned type if a rounding rule other than `.down`, `.towardZero`, or
-  /// `.requireExact` is used. For example:
-  ///
-  ///     let a: UInt = 5
-  ///     let b: UInt = 3
-  ///     let q = a.divided(by: b, rounding: .up) // 2
-  ///     let r = a - b*q // 5 - 3*2 overflows UInt.
-  ///
+  /// unsigned type if a rounding rule other than ``RoundingRule/down``,
+  /// ``RoundingRule/towardZero``, or ``RoundingRule/requireExact`` is
+  /// used. For example:
+  /// ```swift
+  /// let a: UInt = 5
+  /// let b: UInt = 3
+  /// let q = a.divided(by: b, rounding: .up) // 2
+  /// let r = a - b*q // 5 - 3*2 overflows UInt.
+  /// ```
   /// For this reason, there is no `remainder(dividingBy:rounding:)`
   /// operation defined on `BinaryInteger`. Signed integers do not have
-  /// this problem, so it is defined on the `SignedInteger` protocol
-  /// instead, as is an overload of `divided(by:rounding:)` that returns
-  /// both quotient and remainder.
+  /// this problem, so the `SignedInteger` protocol is extended with
+  /// ``SignedInteger/divided(by:rounding:)`` returning both quotient
+  /// and remainder.
   @inlinable
   public func divided(
     by other: Self,
@@ -52,7 +55,7 @@ extension BinaryInteger {
     // rounded toward zero.
     //
     // If we subtract 1 from q, we add other to r to compensate, because:
-    //
+    // 
     //   self = q*other + r
     //        = (q-1)*other + (r+other)
     //
@@ -151,10 +154,10 @@ extension SignedInteger {
   /// Divides `self` by `other`, rounding the quotient according to `rule`,
   /// and returns the remainder.
   ///
-  /// The default rounding rule is `.down`, which _is not the same_ as the
-  /// behavior of the `%` operator from the Swift standard library, but is
-  /// chosen because it generally produces a more useful remainder. To
-  /// match the behavior of `%`, use the `.towardZero` rounding mode.
+  /// The default rounding rule is ``RoundingRule/down``, which _is not the
+  /// same_ as the behavior of the `%` operator from the Swift standard
+  /// library, but is chosen because it generally produces a more useful
+  /// remainder. To match the behavior of `%`, use ``RoundingRule/towardZero``.
   ///
   /// - Precondition: `other` cannot be zero.
   @inlinable
@@ -170,10 +173,10 @@ extension SignedInteger {
   /// Divides `self` by `other`, rounding the quotient according to `rule`,
   /// and returns both the quotient and remainder.
   ///
-  /// The default rounding rule is `.down`, which _is not the same_ as the
-  /// behavior of the `/` operator from the Swift standard library, but is
-  /// chosen because it generally produces a more useful remainder. To
-  /// match the behavior of `/`, use the `.towardZero` rounding mode.
+  /// The default rounding rule is ``RoundingRule/down``, which _is not the
+  /// same_ as the behavior of the `%` operator from the Swift standard
+  /// library, but is chosen because it generally produces a more useful
+  /// remainder. To match the behavior of `/`, use ``RoundingRule/towardZero``.
   ///
   /// Because the default rounding mode does not match Swift's standard
   /// library, this function is a disfavored overload of `divided(by:)`

Sources/IntegerUtilities/SaturatingArithmetic.swift

@@ -31,8 +31,8 @@ extension FixedWidthInteger {
   /// let c = a.addingWithSaturation(b)
   /// ```
   ///
-  /// Anytime the "normal addition" `self + other` does not trap,
-  /// `addingWithSaturation` produces the same result.
+  /// If the "normal addition" `self + other` does not trap,
+  /// this method produces the same result.
   @inlinable
   public func addingWithSaturation(_ other: Self) -> Self {
     let (wrapped, overflow) = addingReportingOverflow(other)
@@ -54,8 +54,8 @@ extension FixedWidthInteger {
   /// `a.subtractingWithSaturation(b)`, because `-b` is not representable
   /// if `b` is the minimum value of a signed type.
   ///
-  /// Anytime the "normal subtraction" `self - other` does not trap,
-  /// `subtractingWithSaturation` produces the same result.
+  /// If the "normal subtraction" `self - other` does not trap,
+  /// this method produces the same result.
   @inlinable
   public func subtractingWithSaturation(_ other: Self) -> Self {
     let (wrapped, overflow) = subtractingReportingOverflow(other)
@@ -85,8 +85,8 @@ extension FixedWidthInteger {
   /// let c = a.multipliedWithSaturation(by: b)
   /// ```
   ///
-  /// Anytime the "normal multiplication" `self * other` does not trap,
-  /// `multipliedWithSaturation` produces the same result.
+  /// If the "normal multiplication" `self * other` does not trap,
+  /// this method produces the same result.
   @inlinable
   public func multipliedWithSaturation(by other: Self) -> Self {
     let (high, low) = multipliedFullWidth(by: other)
@@ -100,12 +100,12 @@ extension FixedWidthInteger {
   /// `self` multiplied by the rational number 2^(`count`), saturated to the
   /// range `Self.min ... Self.max`, and rounded according to `rule`.
   ///
-  /// See `shifted(rightBy:rounding:)` for more discussion of rounding
-  /// shifts with examples.
+  /// See `shifted(rightBy:rounding:)`, defined on `BinaryInteger`, for more
+  /// discussion of rounding shifts with examples.
   ///
   /// - Parameters:
-  ///   - leftBy count: the number of bits to shift by. If positive, this is a left-shift,
-  ///   and if negative a right shift.
+  ///   - leftBy count: the number of bits to shift by. If positive, this is
+  ///     a left-shift, and if negative a right shift.
   ///   - rounding rule: the direction in which to round if `count` is negative.
   @inlinable
   public func shiftedWithSaturation(

Sources/IntegerUtilities/ShiftWithRounding.swift

@@ -12,8 +12,8 @@
 extension BinaryInteger {
   /// `self` divided by 2^(`count`), rounding the result according to `rule`.
   ///
-  /// The default rounding rule is `.down`, which matches the behavior of
-  /// the `>>` operator from the standard library.
+  /// The default rounding rule is ``RoundingRule/down``, which matches the
+  /// behavior of the `>>` operator from the standard library.
   ///
   /// Some examples of different rounding rules:
   ///
@@ -138,8 +138,8 @@ extension BinaryInteger {
 
   /// `self` divided by 2^(`count`), rounding the result according to `rule`.
   ///
-  /// The default rounding rule is `.down`, which matches the behavior of
-  /// the `>>` operator from the standard library.
+  /// The default rounding rule is ``RoundingRule/down``, which matches the
+  /// behavior of the `>>` operator from the standard library.
   ///
   /// Some examples of different rounding rules:
   ///

Sources/RealModule/AlgebraicField.swift

@@ -40,7 +40,7 @@
 /// See also `Real`, `SignedNumeric`, `Numeric` and `AdditiveArithmetic`.
 ///
 /// [field]: https://en.wikipedia.org/wiki/Field_(mathematics)
-public protocol AlgebraicField: SignedNumeric {
+public protocol AlgebraicField: SignedNumeric where Magnitude: AlgebraicField {
 
   /// Replaces a with the (approximate) quotient `a/b`.
   static func /=(a: inout Self, b: Self)

Sources/RealModule/AugmentedArithmetic.swift

@@ -9,11 +9,8 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A namespace for "augmented arithmetic" operations for types conforming to
-/// `Real`.
-///
-/// Augmented arithmetic refers to a family of algorithms that represent
-/// the results of floating-point computations using multiple values such that
+/// Augmented arithmetic provides a family of algorithms that represent the
+/// results of floating-point computations using multiple values such that
 /// either the error is minimized or the result is exact.
 public enum Augmented { }
 

Sources/RealModule/ElementaryFunctions.swift

@@ -9,7 +9,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A type that has elementary functions available.
+/// A type that has elementary functions (`sin`, `cos`, etc.) available.
 ///
 /// An ["elementary function"][elfn] is a function built up from powers, roots,
 /// exponentials, logarithms, trigonometric functions (sin, cos, tan) and