Changes from review feedback.

Author: stephentyrone

Sources/ComplexModule/Documentation.docc/Complex.md

@@ -6,20 +6,24 @@
 
 A `Complex` value is represented with two `RealType` values, corresponding to
 the real and imaginary parts of the number:
+
 ```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 is 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.
 
 - ``init(_:_:)``

Sources/ComplexModule/Documentation.docc/ComplexModule.md

@@ -7,6 +7,7 @@ Types and operations for working with complex numbers.
 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
@@ -32,32 +33,42 @@ map them into Swift types by converting pointers.
 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. There are two
-reasons for this choice. First, Swift generally avoids mixed-type
-arithmetic, period. Second, mixed-type arithmetic operators lead to
-undesirable behavior in common expressions when combined with literal
-type inference. Consider the following example:
+
+The `Complex` type does not provide such mixed operators:
+
 ```swift
-let a: Double = 1
-let b = 2*a
+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>'
 ```
-If we had a heterogeneous `*` operator defined, then if there's no prevailing
-type context (i.e. we aren't in an extension on some type), the expression
-`2*a` is ambiguous; `2` could be either a `Double` or `Complex<Double>`. In
-a `Complex` context, the situation is even worse: `2*a` is inferred to have
-type `Complex`.
-
-Therefore, the `Complex` type does not have these operators. In order to write
-the example from C above, you would use an explicit conversion:
+
+In order to write the example from C above in Swift, you have to perform an
+explicit conversion:
+
 ```swift
-import ComplexModule
 let r = 1.0
-let z = Complex<Double>(0, 2)
-let w = Complex(r) + z
+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 `Compex`).

Sources/ComplexModule/Documentation.docc/Infinity.md

@@ -19,17 +19,21 @@ 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

Sources/ComplexModule/Documentation.docc/Magnitude.md

@@ -62,6 +62,7 @@ However, there are good reasons to make a different choice:
 
 For these reasons, the `magnitude` property of `Complex` binds the
 maximum norm:
+
 ```swift
 Complex(2, 3).magnitude    // 3
 Complex(-1, 0.5).magnitude // 1
@@ -92,6 +93,7 @@ The `length` property takes special care to produce an accurate answer,
 even when the value is poorly-scaled. The naive expression for `length`
 would be `sqrt(x*x + y*y)`, but this can overflow or underflow even when
 the final result should be a finite number.
+
 ```swift
 // Suppose that length were implemented like this:
 extension Complex {