Massage docc files to make the Documentation check happier

Author: stephentyrone

Sources/ComplexModule/Complex.swift

@@ -185,7 +185,7 @@ extension Complex {
     self.init(real, 0)
   }
 
-  /// The complex number with specified imaginary part and zero real part.
+  /// The complex number with zero real part and specified imaginary part.
   ///
   /// Equivalent to `Complex(0, imaginary)`.
   @inlinable

Sources/ComplexModule/Documentation.docc/Complex.md

@@ -1,8 +1,9 @@
 # ``Complex``
 
-A Complex number type that conforms to ``AlgebraicField`` (so all the normal
-arithmetic operations are available) and ``ElementaryFunctions`` (so all
-the usual math functions are available).
+A Complex number type that conforms to `AlgebraicField`
+(so all the normal arithmetic operations are available) and
+`ElementaryFunctions` (so all the usual math functions are
+available).
 
 A `Complex` value is represented with two `RealType` values, corresponding to
 the real and imaginary parts of the number.
@@ -42,7 +43,7 @@ details.
 - ``imaginary``
 - ``rawStorage``
 - ``init(_:_:)``
-- ``init(_:)-(RealType)``
+- ``init(_:)-5aesj``
 - ``init(imaginary:)``
 
 ### Phase, length and magnitude

Sources/ComplexModule/Documentation.docc/ComplexModule.md

@@ -2,7 +2,9 @@
 
 Types and operations for working with complex numbers.
 
-## Representation
+## Overview
+
+### Representation
 
 The `Complex` type is generic over an associated `RealType`; complex numbers
 are represented as two `RealType` values, the real and imaginary parts of the
@@ -28,7 +30,7 @@ Functions taking complex arguments in these other languages are not
 automatically converted on import, but you can safely write shims that
 map them into Swift types by converting pointers.
 
-## Real-Complex arithmetic
+### Real-Complex arithmetic
 
 Because the real numbers are a subset of the complex numbers, many
 languages support arithmetic with mixed real and complex operands.

Sources/ComplexModule/Documentation.docc/Infinity.md

@@ -3,6 +3,8 @@
 Semantics of `Complex` zero and infinity values, and important considerations
 when porting code from other languages.
 
+## Overview
+
 Unlike C and C++'s complex types, `Complex` does not attempt to make a 
 semantic distinction between different infinity and NaN values. Any `Complex`
 datum with a non-finite component is treated as the "point at infinity" on 
@@ -12,7 +14,7 @@ As a consequence, all values with either component infinite or NaN compare
 equal, and hash the same. Similarly, all zero values compare equal and hash
 the same.
 
-## Rationale
+### Rationale
 
 This choice has some drawbacks,¹ but also some significant advantages.
 In particular, complex multiplication is the most common operation performed

Sources/ComplexModule/Documentation.docc/Magnitude.md

@@ -3,6 +3,8 @@
 Introduction to the concept of norm and discussion of the `Complex` type's
 `.magnitude` property.
 
+## Overview
+
 In mathematics, a *norm* is a function that gives each element of a vector
 space a non-negative length.¹
 
@@ -33,7 +35,7 @@ The three most commonly-used norms are:
 The `Complex` type gives special names to two of these norms; `length`
 for the 2-norm, and `magnitude` for the ∞-norm.
 
-## Magnitude:
+### Magnitude:
 
 The `Numeric` protocol requires us to choose a norm to call `magnitude`,
 but does not give guidance as to which one we should pick. The easiest choice
@@ -68,7 +70,7 @@ Complex(2, 3).magnitude    // 3
 Complex(-1, 0.5).magnitude // 1
 ```
 
-## Length:
+### Length:
 
 The `length` property of a `Complex` value is its Euclidean norm.
 

Sources/RealModule/AugmentedArithmetic.swift

@@ -9,6 +9,7 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// Namespace for augmented arithmetic operations.
 public enum Augmented { }
 
 extension Augmented {
@@ -96,10 +97,11 @@ extension Augmented {
   /// error from that computation rounded to the closest representable
   /// value.
   ///
-  /// Unlike ``sum(large:small:)``, the magnitude of the summands does not
-  /// matter. If you know statically that `a.magnitude >= b.magnitude`, you
-  /// should use ``sum(large:small:)``. If you do not have such a static
-  /// bound, you should use this function instead.
+  /// The magnitude of the summands does not change the result of this
+  /// operation. If you know statically that `a.magnitude >= b.magnitude`,
+  /// you may want to consider using ``sum(large:small:)`` to get the same
+  /// result somewhat more efficiently. If you do not have such a static
+  /// bound, you usually want to use this function instead.
   ///
   /// Unlike ``product(_:_:)``, the rounding error of a sum never underflows.
   ///

Sources/RealModule/Documentation.docc/Augmented.md

@@ -1,5 +1,9 @@
 # ``Augmented``
 
+A namespace for a family of algorithms that compute the results of floating-
+point arithmetic using multiple values such that either the error is minimized
+or the result is exact.
+
 ## Overview
 
 Consider multiplying two Doubles. A Double has 53 significand bits, so their
@@ -17,4 +21,11 @@ the low-order part of the product suddenly becomes significant:
 let result = 1 - c      // exactly zero, but "should be" 2⁻¹⁰⁴
 ```
 Augmented arithmetic is a building-block that library writers can use to
-handle cases like this more carefully.
+handle cases like this more carefully. For the example above, one might
+compute:
+```swift
+let (head, tail) = Augmented.product(a,b)
+```
+`head` is then 1.0 and `tail` is -2⁻¹⁰⁴, so no information has been lost.
+Of course, the result is now split across two Doubles instead of one, but the
+information in `tail` can be carried forward into future computations.

Sources/RealModule/Documentation.docc/Relaxed.md

@@ -1,5 +1,8 @@
 # ``Relaxed``
 
+A namespace for a family of operations that "relax" the usual rules for
+floating-point to allow reassociation of arithmetic and FMA formation.
+
 ## Overview
 
 Because of rounding, and the arithmetic rules for infinity and NaN values,