Merge pull request #182 from stephentyrone/more-documentation-for-1.0

Add some documentation for AlgebraicField ops, minor fix for Augmented.

Author: stephentyrone

Sources/RealModule/AlgebraicField.swift

@@ -47,8 +47,10 @@
 /// [field]: https://en.wikipedia.org/wiki/Field_(mathematics)
 public protocol AlgebraicField: SignedNumeric {
 
+  /// Replaces a with the (approximate) quotient `a/b`.
   static func /=(a: inout Self, b: Self)
 
+  /// The (approximate) quotient `a/b`.
   static func /(a: Self, b: Self) -> Self
 
   /// The (approximate) reciprocal (multiplicative inverse) of this number,
@@ -59,11 +61,14 @@ public protocol AlgebraicField: SignedNumeric {
   /// (for finite fields) or approximately the same result up to a typical
   /// rounding error (for floating-point formats).
   ///
-  /// If self is zero, or if a reciprocal would overflow or underflow such
-  /// that it cannot be accurately represented, the result is nil. Note that
-  /// `.zero.reciprocal`, somewhat surprisingly, is *not* nil for `Real` or
-  /// `Complex` types, because these types have an `.infinity` value that
-  /// acts as the reciprocal of `.zero`.
+  /// If self is zero and the type has no representation for infinity (as
+  /// in a typical finite field implementation), or if a reciprocal would
+  /// overflow or underflow such that it cannot be accurately represented,
+  /// the result is nil.
+  ///
+  /// Note that `.zero.reciprocal`, somewhat surprisingly, is *not* nil
+  /// for `Real` or `Complex` types, because these types have an
+  /// `.infinity` value that acts as the reciprocal of `.zero`.
   var reciprocal: Self? { get }
 }
 

Sources/RealModule/AugmentedArithmetic.swift

@@ -40,8 +40,8 @@ extension Augmented {
   ///
   /// Postconditions:
   /// -
-  /// - If `head` is normal, then `abs(tail) < abs(head.ulp)`.
-  ///   Assuming IEEE 754 default rounding, `abs(tail) <= abs(head.ulp)/2`.
+  /// - If `head` is normal, then `abs(tail) < head.ulp`.
+  ///   Assuming IEEE 754 default rounding, `abs(tail) <= head.ulp/2`.
   /// - If both `head` and `tail` are normal, then `a * b` is exactly
   ///   equal to `head + tail` when computed as real numbers.
   @_transparent
@@ -84,8 +84,8 @@ extension Augmented {
   ///
   /// Postconditions:
   /// -
-  /// - If `head` is normal, then `abs(tail) < abs(head.ulp)`.
-  ///   Assuming IEEE 754 default rounding, `abs(tail) <= abs(head.ulp)/2`.
+  /// - If `head` is normal, then `abs(tail) < head.ulp`.
+  ///   Assuming IEEE 754 default rounding, `abs(tail) <= head.ulp/2`.
   @_transparent
   public static func sum<T:Real>(large a: T, small b: T) -> (head: T, tail: T) {
     assert(!(b.magnitude > a.magnitude))

Sources/RealModule/Real.swift

@@ -99,6 +99,11 @@ extension Real {
     return x.squareRoot()
   }
 
+  /// The (approximate) reciprocal (multiplicative inverse) of this number,
+  /// if it is representable.
+  ///
+  /// If `a` if finite and nonzero, and `1/a` overflows or underflows,
+  /// then `a.reciprocal` is `nil`. Otherwise, `a.reciprcoal` is `1/a`.
   @inlinable
   public var reciprocal: Self? {
     let recip = 1/self