Massage docc files to make the Documentation check happier

This commit is contained in:
Stephen Canon committed 2025-08-11 18:11:44 -04:00
1 parent acbf4257ca
commit 9c548804c8
8 files changed
+38 -15

No files matched your search

+1 -1
View File
@@ -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
@@ -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
@@ -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.
@@ -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
@@ -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.
+6 -4
View File
@@ -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.
///
@@ -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.
@@ -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,