Merge pull request #224 from apple/documentation-formatting

Minor documentation formatting cleanup.

Author: stephentyrone

Sources/ComplexModule/Complex+AlgebraicField.swift

@@ -111,7 +111,7 @@ extension Complex: AlgebraicField {
   /// ```
   ///
   /// Error Bounds:
-  /// -
+  ///
   /// Unlike real types, when working with complex types, multiplying by the
   /// reciprocal instead of dividing cannot change the result. If the
   /// reciprocal is non-nil, the two computations are always equivalent.

Sources/ComplexModule/Complex+Numeric.swift

@@ -47,9 +47,7 @@ extension Complex: Numeric {
   /// - If `z` is zero, `z.magnitude` is `0`.
   /// - Otherwise, `z.magnitude` is finite and non-zero.
   ///
-  /// See also:
-  /// - `.length`
-  /// - `.lengthSquared`
+  /// See also `.length` and `.lengthSquared`.
   @_transparent
   public var magnitude: RealType {
     guard isFinite else { return .infinity }

Sources/ComplexModule/Complex.swift

@@ -16,7 +16,7 @@ import RealModule
 /// TODO: introductory text on complex numbers
 ///
 /// Implementation notes:
-/// -
+///
 /// This type does not provide heterogeneous real/complex arithmetic,
 /// not even the natural vector-space operations like real * complex.
 /// There are two reasons for this choice: first, Swift broadly avoids
@@ -105,23 +105,15 @@ extension Complex {
 extension Complex {
   /// The imaginary unit.
   ///
-  /// See also:
-  /// -
-  /// - .zero
-  /// - .one
-  /// - .infinity
+  /// See also `.zero`, `.one` and `.infinity`.
   @_transparent
   public static var i: Complex {
     Complex(0, 1)
   }
 
   /// The point at infinity.
   ///
-  /// See also:
-  /// -
-  /// - .zero
-  /// - .one
-  /// - .i
+  /// See also `.zero`, `.one` and `.i`.
   @_transparent
   public static var infinity: Complex {
     Complex(.infinity, 0)
@@ -131,11 +123,7 @@ extension Complex {
   ///
   /// A complex value is finite if neither component is an infinity or nan.
   ///
-  /// See also:
-  /// -
-  /// - `.isNormal`
-  /// - `.isSubnormal`
-  /// - `.isZero`
+  /// See also `.isNormal`, `.isSubnormal` and `.isZero`.
   @_transparent
   public var isFinite: Bool {
     x.isFinite && y.isFinite
@@ -148,10 +136,7 @@ extension Complex {
   /// one of the components is normal if its exponent allows a full-precision
   /// representation.
   ///
-  /// See also:
-  /// - `.isFinite`
-  /// - `.isSubnormal`
-  /// - `.isZero`
+  /// See also `.isFinite`, `.isSubnormal` and `.isZero`.
   @_transparent
   public var isNormal: Bool {
     isFinite && (x.isNormal || y.isNormal)
@@ -163,10 +148,7 @@ extension Complex {
   /// When the result of a computation is subnormal, underflow has occurred and
   /// the result generally does not have full precision.
   ///
-  /// See also:
-  /// - `.isFinite`
-  /// - `.isNormal`
-  /// - `.isZero`
+  /// See also `.isFinite`, `.isNormal` and `.isZero`.
   @_transparent
   public var isSubnormal: Bool {
     isFinite && !isNormal && !isZero
@@ -177,11 +159,7 @@ extension Complex {
   /// A complex number is zero if *both* the real and imaginary components
   /// are zero.
   ///
-  /// See also:
-  /// -
-  /// - `.isFinite`
-  /// - `.isNormal`
-  /// - `.isSubnormal`
+  /// See also `.isFinite`, `.isNormal` and `isSubnormal`.
   @_transparent
   public var isZero: Bool {
     x == 0 && y == 0

Sources/ComplexModule/Polar.swift

@@ -31,16 +31,10 @@ extension Complex {
   /// a representable result.
   ///
   /// Edge cases:
-  /// -
-  /// If a complex value is not finite, its `.length` is `infinity`.
-  ///
-  /// See also:
-  /// -
-  /// - `.magnitude`
-  /// - `.lengthSquared`
-  /// - `.phase`
-  /// - `.polar`
-  /// - `init(r:θ:)`
+  /// - If a complex value is not finite, its `.length` is `infinity`.
+  ///
+  /// See also `.magnitude`, `.lengthSquared`, `.phase`, `.polar`
+  /// and `init(r:θ:)`.
   @_transparent
   public var length: RealType {
     let naive = lengthSquared
@@ -69,10 +63,7 @@ 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`
-  /// - `.magnitude`
+  /// See also `.length` and `.magnitude`.
   @_transparent
   public var lengthSquared: RealType {
     x*x + y*y
@@ -88,14 +79,9 @@ extension Complex {
   /// and `nan` is returned.
   ///
   /// Edge cases:
-  /// -
-  /// If the complex value is zero or non-finite, phase is `nan`.
-  ///
-  /// See also:
-  /// -
-  /// - `.length`
-  /// - `.polar`
-  /// - `init(r:θ:)`
+  /// - If the complex value is zero or non-finite, phase is `nan`.
+  ///
+  /// See also `.length`, `.polar` and `init(r:θ:)`.
   @inlinable
   public var phase: RealType {
     guard isFinite && !isZero else { return .nan }
@@ -105,23 +91,17 @@ extension Complex {
   /// The length and phase (or polar coordinates) of this value.
   ///
   /// Edge cases:
-  /// -
-  /// If the complex value is zero or non-finite, phase is `.nan`.
-  /// If the complex value is non-finite, length is `.infinity`.
-  ///
-  /// See also:
-  /// -
-  /// - `.length`
-  /// - `.phase`
-  /// - `init(r:θ:)`
+  /// - If the complex value is zero or non-finite, phase is `.nan`.
+  /// - If the complex value is non-finite, length is `.infinity`.
+  ///
+  /// See also: `.length`, `.phase` and `init(r:θ:)`.
   public var polar: (length: RealType, phase: RealType) {
     (length, phase)
   }
 
   /// Creates a complex value specified with polar coordinates.
   ///
   /// Edge cases:
-  /// -
   /// - Negative lengths are interpreted as reflecting the point through the
   ///   origin, i.e.:
   ///   ```
@@ -137,11 +117,7 @@ extension Complex {
   ///   ```
   /// - Otherwise, `θ` must be finite, or a precondition failure occurs.
   ///
-  /// See also:
-  /// -
-  /// - `.length`
-  /// - `.phase`
-  /// - `.polar`
+  /// See also `.length`, `.phase` and `.polar`.
   @inlinable
   public init(length: RealType, phase: RealType) {
     if phase.isFinite {

Sources/RealModule/AlgebraicField.swift

@@ -37,12 +37,7 @@
 /// If a type `T` conforms to the `Real` protocol, then `T` and `Complex<T>`
 /// both conform to `AlgebraicField`.
 ///
-/// See Also:
-/// -
-/// - Real
-/// - SignedNumeric
-/// - Numeric
-/// - AdditiveArithmetic
+/// See also `Real`, `SignedNumeric`, `Numeric` and `AdditiveArithmetic`.
 ///
 /// [field]: https://en.wikipedia.org/wiki/Field_(mathematics)
 public protocol AlgebraicField: SignedNumeric {

Sources/RealModule/ApproximateEquality.swift

@@ -28,8 +28,7 @@ extension Numeric where Magnitude: FloatingPoint {
   /// is not suitable for all use cases.
   ///
   /// Mathematical Properties:
-  /// ------------------------
-  /// 
+  ///
   /// - `isApproximatelyEqual(to:relativeTolerance:norm:)` is _reflexive_ for
   ///   non-exceptional values (such as NaN).
   ///
@@ -51,9 +50,7 @@ extension Numeric where Magnitude: FloatingPoint {
   ///   so long as no underflow or overflow has occured, and no exceptional
   ///   value is produced by the scaling.
   ///
-  /// See Also:
-  /// -------
-  /// - `isApproximatelyEqual(to:absoluteTolerance:[relativeTolerance:norm:])`
+  /// See also `isApproximatelyEqual(to:absoluteTolerance:[relativeTolerance:norm:])`.
   ///
   /// - Parameters:
   ///
@@ -98,7 +95,6 @@ extension Numeric where Magnitude: FloatingPoint {
   /// where `scale` is `max(self.magnitude, other.magnitude)`.
   ///
   /// Mathematical Properties:
-  /// ------------------------
   ///
   /// - `isApproximatelyEqual(to:absoluteTolerance:relativeTolerance:)`
   ///   is _reflexive_ for non-exceptional values (such as NaN).
@@ -118,9 +114,7 @@ extension Numeric where Magnitude: FloatingPoint {
   ///   to `a` is _convex_. (Under the assumption that `norm` implements a
   ///   valid norm, which cannot be checked by this function.)
   ///
-  /// See Also:
-  /// -------
-  /// - `isApproximatelyEqual(to:[relativeTolerance:])`
+  /// See also `isApproximatelyEqual(to:[relativeTolerance:])`.
   ///
   /// - Parameters:
   ///
@@ -170,7 +164,6 @@ extension AdditiveArithmetic {
   /// where `scale` is `max(norm(self), norm(other))`.
   ///
   /// Mathematical Properties:
-  /// ------------------------
   ///
   /// - `isApproximatelyEqual(to:absoluteTolerance:relativeTolerance:norm:)`
   ///   is _reflexive_ for non-exceptional values (such as NaN).
@@ -191,10 +184,8 @@ extension AdditiveArithmetic {
   ///   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:
-  /// -------
-  /// - `isApproximatelyEqual(to:[relativeTolerance:norm:])`
-  /// - `isApproximatelyEqual(to:absoluteTolerance:[relativeTolerance:])`
+  /// See also `isApproximatelyEqual(to:[relativeTolerance:norm:])` and
+  /// `isApproximatelyEqual(to:absoluteTolerance:[relativeTolerance:])`.
   ///
   /// - Parameters:
   ///

Sources/RealModule/AugmentedArithmetic.swift

@@ -28,7 +28,7 @@ extension Augmented {
   /// This operation is sometimes called "twoProd" or "twoProduct".
   ///
   /// Edge Cases:
-  /// -
+  ///
   /// - `head` is always the IEEE 754 product `a * b`.
   /// - If `head` is not finite, `tail` is unspecified and should not be
   ///   interpreted as having any meaning (it may be `NaN` or `infinity`).
@@ -39,7 +39,7 @@ extension Augmented {
   /// - If `head` is zero, `tail` is also a zero with unspecified sign.
   ///
   /// Postconditions:
-  /// -
+  ///
   /// - 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
@@ -61,8 +61,7 @@ extension Augmented {
   /// value.
   ///
   /// Unlike `Augmented.product(a, b)`, the rounding error of a sum can
-  /// never underflow. However, it may not be exactly representable when
-  /// `a` and `b` differ widely in magnitude.
+  /// never underflow.
   ///
   /// This operation is sometimes called ["fastTwoSum"].
   ///
@@ -71,19 +70,19 @@ extension Augmented {
   ///   - b: The summand with smaller magnitude.
   ///
   /// Preconditions:
-  /// -
+  ///
   /// - `large.magnitude` must not be smaller than `small.magnitude`.
   ///   They may be equal, or one or both may be `NaN`.
   ///   This precondition is only enforced in debug builds.
   ///
   /// Edge Cases:
-  /// -
+  ///
   /// - `head` is always the IEEE 754 sum `a + b`.
   /// - If `head` is not finite, `tail` is unspecified and should not be
   ///   interpreted as having any meaning (it may be `NaN` or `infinity`).
   ///
   /// Postconditions:
-  /// -
+  ///
   /// - If `head` is normal, then `abs(tail) < head.ulp`.
   ///   Assuming IEEE 754 default rounding, `abs(tail) <= head.ulp/2`.
   ///
@@ -112,8 +111,7 @@ extension Augmented {
   /// over this function; as it faster to calculate.
   ///
   /// Unlike `Augmented.product(a, b)`, the rounding error of a sum can
-  /// never underflow. However, it may not be exactly representable when
-  /// `a` and `b` differ widely in magnitude.
+  /// never underflow.
   ///
   /// This operation is sometimes called ["twoSum"].
   ///
@@ -122,13 +120,13 @@ extension Augmented {
   ///   - b: The other summand
   ///
   /// Edge Cases:
-  /// -
+  ///
   /// - `head` is always the IEEE 754 sum `a + b`.
   /// - If `head` is not finite, `tail` is unspecified and should not be
   ///   interpreted as having any meaning (it may be `NaN` or `infinity`).
   ///
   /// Postconditions:
-  /// -
+  /// 
   /// - If `head` is normal, then `abs(tail) < head.ulp`.
   ///   Assuming IEEE 754 default rounding, `abs(tail) <= head.ulp/2`.
   ///