Various documentation improvements.

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/Complex.swift

@@ -11,39 +11,11 @@
 
 import RealModule
 
-/// A complex number represented by real and imaginary parts.
+/// A [complex number](https://en.wikipedia.org/wiki/Complex_number).
 ///
-/// 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
-/// mixed-type arithmetic when the operation can be adequately expressed
-/// by a conversion and homogeneous arithmetic. Second, with the current
-/// typechecker rules, it would lead to undesirable ambiguity in common
-/// expressions (see README.md for more details).
-///
-/// Unlike C's `_Complex` and C++'s `std::complex<>` types, we do not
-/// attempt to make meaningful semantic distinctions between different
-/// representations of infinity or NaN. Any Complex value with at least
-/// one non-finite component is simply "non-finite". In as much as
-/// possible, we use the semantics of the point at infinity on the
-/// Riemann sphere for such values. This approach simplifies the number of
-/// edge cases that need to be considered for multiplication, division, and
-/// the elementary functions considerably.
-///
-/// `.magnitude` does not return the Euclidean norm; it uses the "infinity
-/// norm" (`max(|real|,|imaginary|)`) instead. There are two reasons for this
-/// choice: first, it's simply faster to compute on most hardware. Second,
-/// there exist values for which the Euclidean norm cannot be represented
-/// (consider a number with `.real` and `.imaginary` both equal to
-/// `RealType.greatestFiniteMagnitude`; the Euclidean norm would be
-/// `.sqrt(2) * .greatestFiniteMagnitude`, which overflows). Using
-/// the infinity norm avoids this problem entirely without significant
-/// downsides. You can access the Euclidean norm using the `length`
-/// property.
+/// `Complex` is an `AlgebraicField`, so it has all the normal arithmetic
+/// operators. It conforms to `ElementaryFunctions`, so it has all the usual
+/// math functions.
 @frozen
 public struct Complex<RealType> where RealType: Real {
   //  A note on the `x` and `y` properties
@@ -53,11 +25,11 @@ public struct Complex<RealType> where RealType: Real {
   //  `.real` and `.imaginary` properties, which wrap this storage and
   //  fixup the semantics for non-finite values.
 
-  /// The real component of the value.
+  /// The storage for the real component of the value.
   @usableFromInline @inline(__always)
   internal var x: RealType
 
-  /// The imaginary part of the value.
+  /// The storage for the imaginary part of the value.
   @usableFromInline @inline(__always)
   internal var y: RealType
 
@@ -95,11 +67,24 @@ extension Complex {
     set { y = newValue }
   }
 
+  /// The raw representation of the value.
+  ///
+  /// Use this when you need the underlying RealType values,
+  /// without fixup for NaN or infinity.
+  public var rawStorage: (x: RealType, y: RealType) {
+    @_transparent
+    get { (x, y) }
+    @_transparent
+    set { (x, y) = newValue }
+  }
+
   /// The raw representation of the real part of this value.
+  @available(*, deprecated, message: "Use rawStorage")
   @_transparent
   public var _rawX: RealType { x }
 
   /// The raw representation of the imaginary part of this value.
+  @available(*, deprecated, message: "Use rawStorage")
   @_transparent
   public var _rawY: RealType { y }
 }
@@ -200,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

@@ -0,0 +1,70 @@
+# ``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` value is represented with two `RealType` values, corresponding to
+the real and imaginary parts of the number.
+
+You can access these Cartesian components using the real and imaginary
+properties.
+
+```swift
+let z = Complex(1,-1) //  1 - i
+let re = z.real       //  1
+let im = z.imaginary  // -1
+```
+
+All `Complex` numbers with a non-finite component are treated as a single
+"point at infinity," with infinite magnitude and indeterminant phase. Thus,
+the real and imaginary parts of an infinity are nan.
+
+```swift
+let w = Complex<Double>.infinity
+w == -w               // true
+let re = w.real       // .nan
+let im = w.imag       // .nan
+```
+
+See <doc:Infinity> for more details.
+
+The ``magnitude`` property of a complex number is the infinity norm of the
+value (a.k.a. “maximum norm” or “Чебышёв norm”). To get the two norm (a.k.a
+"Euclidean norm"), use the ``length`` property. See <doc:Magnitude> for more
+details.
+
+## Topics 
+
+### Real and imaginary parts
+
+- ``real``
+- ``imaginary``
+- ``rawStorage``
+- ``init(_:_:)``
+- ``init(_:)-5aesj``
+- ``init(imaginary:)``
+
+### Phase, length and magnitude
+
+- ``magnitude``
+- ``length``
+- ``lengthSquared``
+- ``normalized``
+- ``phase``
+- ``polar``
+- ``init(length:phase:)``
+
+### Scaling by real numbers
+- ``multiplied(by:)``
+- ``divided(by:)``
+
+### Complex-specific operations
+- ``conjugate``
+
+### Classification
+- ``isZero``
+- ``isSubnormal``
+- ``isNormal``
+- ``isFinite``

Sources/ComplexModule/Documentation.docc/ComplexModule.md

@@ -0,0 +1,88 @@
+# ``ComplexModule``
+
+Types and operations for working with complex numbers.
+
+## 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
+number.
+
+```
+let z = Complex<Double>(1, 2)
+let re = z.real
+let im = z.imaginary
+```
+
+### Memory layout
+
+A `Complex` value is stored as two `RealType` values arranged consecutively
+in memory. Thus it has the same memory layout as:
+- A Fortran complex value built on the corresponding real type (as used
+by BLAS and LAPACK).
+- A C struct with real and imaginary parts and nothing else (as used by
+computational libraries predating C99).
+- A C99 `_Complex` value built on the corresponding real type.
+- A C++ `std::complex` value built on the corresponding real type.
+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
+
+Because the real numbers are a subset of the complex numbers, many
+languages support arithmetic with mixed real and complex operands.
+For example, C allows the following:
+
+```c
+#include <complex.h>
+double r = 1;
+double complex z = CMPLX(0, 2); // 2i
+double complex w = r + z;       // 1 + 2i
+```
+
+The `Complex` type does not provide such mixed operators:
+
+```swift
+let r = 1.0
+let z = Complex(imaginary: 2.0)
+let w = r + z // error: binary operator '+' cannot be applied to operands of type 'Double' and 'Complex<Double>'
+```
+
+In order to write the example from C above in Swift, you have to perform an
+explicit conversion:
+
+```swift
+let r = 1.0
+let z = Complex(imaginary: 2.0)
+let w = Complex(r) + z // OK
+```
+
+There are two reasons for this choice. Most importantly, Swift generally avoids
+mixed-type arithmetic. Second, if we _did_ provide such heterogeneous operators,
+it would lead to undesirable behavior in common expressions when combined with
+literal type inference. Consider the following example:
+
+```swift
+let a: Double = 1
+let b = 2*a
+```
+
+`b` ought to have type `Double`, but if we did have a Complex-by-Real `*` 
+operation, `2*a` would either be ambiguous (if there were no type context),
+or be inferred to have type `Complex<Double>` (if the expression appeared
+in the context of an extension defined on `Complex`).
+
+Note that we _do_ provide heterogeneous multiplication and division by a real
+value, spelled as ``Complex/divided(by:)`` and ``Complex/multiplied(by:)``
+to avoid ambiguity.
+
+```swift
+let z = Complex<Double>(1,3)
+let w = z.multiplied(by: 2)
+```
+
+These operations are generally more efficient than converting the scale to
+a complex number and then using `*` or `/`.

Sources/ComplexModule/Documentation.docc/Infinity.md

@@ -0,0 +1,55 @@
+# Zero and infinity
+
+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 
+the Riemann sphere--a value with infinite magnitude and unspecified phase.
+
+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
+
+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
+```
+
+`Complex` can use this implementation, because we do not differentiate between
+infinities and NaN values. C and C++, by contrast, cannot use this
+implementation by default, because, for example:
+
+```
+(1 + ∞i) * (0 - 2i) = (1*0 - ∞*(-2)) + (1*(-2) + ∞*0)i
+                    = (0 - ∞) + (-2 + nan)i
+                    = -∞ + nan i
+```
+
+`Complex` treats this as "infinity", which is the correct result. C and C++
+treat it as a nan value, however, which is incorrect; infinity multiplied
+by a non-zero number should be infinity. Thus, C and C++ (by default) must
+detect these special cases and fix them up, which makes multiplication a
+more computationally expensive operation.²
+
+### Footnotes:
+¹ W. Kahan, Branch Cuts for Complex Elementary Functions, or Much Ado
+About Nothing's Sign Bit. In A. Iserles and M.J.D. Powell, editors,
+_Proceedings The State of Art in Numerical Analysis_, pages 165–211, 1987.
+
+² This can be addressed in C programs by use of the `STDC CX_LIMITED_RANGE`
+pragma, which instructs the compiler to simply not care about these cases.
+Unfortunately, this pragma is not often used in real C or C++ programs
+(though it does see some use in _libraries_). Programmers tend to specify
+`-ffast-math` or maybe `-ffinite-math-only` instead, which has other
+undesirable consequences.