Merge branch 'quaternions' into quaternion/division-algebra

Author: markuswntr

Sources/QuaternionModule/Polar.swift

@@ -46,22 +46,19 @@ extension Quaternion {
   /// a representable result.
   ///
   /// Edge cases:
-  /// -
-  /// If a quaternion is not finite, its `.length` is `infinity`.
+  /// - If a quaternion is not finite, its `.length` is `infinity`.
   ///
-  /// See also:
-  /// -
-  /// - `.magnitude`
-  /// - `.lengthSquared`
+  /// See also `.magnitude`, `.lengthSquared`, `.polar` and
+  /// `init(length:,phase:,axis:)`.
   @_transparent
   public var length: RealType {
     let naive = lengthSquared
     guard naive.isNormal else { return carefulLength }
     return .sqrt(naive)
   }
 
-  //  Internal implementation detail of `length`, moving slow path off
-  //  of the inline function.
+  // Internal implementation detail of `length`, moving slow path off
+  // of the inline function.
   @usableFromInline
   internal var carefulLength: RealType {
     guard isFinite else { return .infinity }
@@ -79,10 +76,8 @@ extension Quaternion {
   ///
   /// This property is more efficient to compute than `length`.
   ///
-  /// See also:
-  /// -
-  /// - `.length`
-  /// - `.magnitude`
+  /// See also `.magnitude`, `.length`, `.polar` and
+  /// `init(length:,phase:,axis:)`.
   @_transparent
   public var lengthSquared: RealType {
     (components * components).sum()
@@ -94,23 +89,15 @@ extension Quaternion {
   /// and the rotation axis as SIMD3 vector of unit length.
   ///
   /// Edge cases:
-  /// -
   /// - If the quaternion is zero, length is `.zero` and angle and axis
   /// are `nan`.
   /// - If the quaternion is non-finite, length is `.infinity` and angle and
   /// axis are `nan`.
   /// - For any length other than `.zero` or `.infinity`, if angle is zero, axis
   /// is `nan`.
   ///
-  /// See also:
-  /// -
-  /// - `.angle`
-  /// - `.axis`
-  /// - `.angleAxis`
-  /// - `.rotationVector`
-  /// - `init(length:angle:axis:)`
-  /// - `init(length:phase:axis)`
-  /// - `init(rotation:)`
+  /// See also `.magnitude`, `.length`, `.lengthSquared` and
+  /// `init(length:,phase:,axis:)`.
   ///
   /// [wiki]: https://en.wikipedia.org/wiki/Polar_decomposition#Quaternion_polar_decomposition
   public var polar: (length: RealType, phase: RealType, axis: SIMD3<RealType>) {
@@ -128,8 +115,8 @@ extension Quaternion {
   /// - Note: `axis` must be of unit length, or an assertion failure occurs.
   ///
   /// Edge cases:
-  /// -
-  /// - Negative lengths are interpreted as reflecting the point through the origin, i.e.:
+  /// - Negative lengths are interpreted as reflecting the point through the
+  ///   origin, i.e.:
   ///   ```
   ///   Quaternion(length: -r, phase: θ, axis: axis) == -Quaternion(length: r, phase: θ, axis: axis)
   ///   ```
@@ -143,15 +130,7 @@ extension Quaternion {
   ///   ```
   /// - Otherwise, `θ` must be finite, or a precondition failure occurs.
   ///
-  /// See also:
-  /// -
-  /// - `.angle`
-  /// - `.axis`
-  /// - `.angleAxis`
-  /// - `.rotationVector`
-  /// - `.polar`
-  /// - `init(length:angle:axis:)`
-  /// - `init(rotation:)`
+  /// See also `.magnitude`, `.length`, `.lengthSquared` and `.polar`.
   ///
   /// [wiki]: https://en.wikipedia.org/wiki/Polar_decomposition#Quaternion_polar_decomposition
   @inlinable
@@ -186,8 +165,7 @@ extension Quaternion {
   /// The half rotation angle in radians within *[0, π]* range.
   ///
   /// Edge cases:
-  /// -
-  /// If the quaternion is zero or non-finite, halfAngle is `nan`.
+  /// - If the quaternion is zero or non-finite, halfAngle is `nan`.
   @usableFromInline @inline(__always)
   internal var halfAngle: RealType {
     guard isFinite else { return .nan }

Sources/QuaternionModule/Quaternion+Numeric.swift

@@ -53,15 +53,11 @@ extension Quaternion: Numeric {
   /// properties instead.
   ///
   /// Edge cases:
-  /// -
   /// - If `q` is not finite, `q.magnitude` is `.infinity`.
   /// - If `q` is zero, `q.magnitude` is `0`.
   /// - Otherwise, `q.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/QuaternionModule/Quaternion.swift

@@ -89,55 +89,31 @@ extension Quaternion {
 
   /// The quaternion with the imaginary unit **i** one, i.e. `0 + i + 0j + 0k`.
   ///
-  /// See also:
-  /// -
-  /// - .zero
-  /// - .one
-  /// - .j
-  /// - .k
-  /// - .infinity
+  /// See also `.zero`, `.one`, `.j`, `.k` and `.infinity`.
   @_transparent
   public static var i: Quaternion {
     Quaternion(imaginary: SIMD3(1,0,0))
   }
 
   /// The quaternion with the imaginary unit **j** one, i.e. `0 + 0i + j + 0k`.
   ///
-  /// See also:
-  /// -
-  /// - .zero
-  /// - .one
-  /// - .i
-  /// - .k
-  /// - .infinity
+  /// See also `.zero`, `.one`, `.i`, `.k` and `.infinity`.
   @_transparent
   public static var j: Quaternion {
     Quaternion(imaginary: SIMD3(0,1,0))
   }
 
   /// The quaternion with the imaginary unit **k** one, i.e. `0 + 0i + 0j + k`.
   ///
-  /// See also:
-  /// -
-  /// - .zero
-  /// - .one
-  /// - .i
-  /// - .j
-  /// - .infinity
+  /// See also `.zero`, `.one`, `.i`, `.j` and `.infinity`.
   @_transparent
   public static var k: Quaternion {
     Quaternion(imaginary: SIMD3(0,0,1))
   }
 
   /// The point at infinity.
   ///
-  /// See also:
-  /// -
-  /// - .zero
-  /// - .one
-  /// - .i
-  /// - .j
-  /// - .k
+  /// See also `.zero`, `.one`, `.i`, `.j` and `.k`.
   @_transparent
   public static var infinity: Quaternion {
     Quaternion(.infinity)
@@ -147,13 +123,7 @@ extension Quaternion {
   ///
   /// A quaternion is finite if neither component is an infinity or nan.
   ///
-  /// See also:
-  /// -
-  /// - `.isNormal`
-  /// - `.isSubnormal`
-  /// - `.isZero`
-  /// - `.isReal`
-  /// - `.isPure`
+  /// See also `.isNormal`, `.isSubnormal`, `.isZero`, `.isReal`, `.isPure`.
   @_transparent
   public var isFinite: Bool {
     return components.x.isFinite
@@ -168,13 +138,7 @@ extension Quaternion {
   /// are normal. A floating-point number representing one of the components is normal
   /// if its exponent allows a full-precision representation.
   ///
-  /// See also:
-  /// -
-  /// - `.isFinite`
-  /// - `.isSubnormal`
-  /// - `.isZero`
-  /// - `.isReal`
-  /// - `.isPure`
+  /// See also `.isFinite`, `.isSubnormal`, `.isZero`, `.isReal`, `.isPure`.
   @_transparent
   public var isNormal: Bool {
     return isFinite && (
@@ -191,13 +155,7 @@ extension Quaternion {
   /// computation is subnormal, underflow has occurred and the result generally does not have full
   /// precision.
   ///
-  /// See also:
-  /// -
-  /// - `.isFinite`
-  /// - `.isNormal`
-  /// - `.isZero`
-  /// - `.isReal`
-  /// - `.isPure`
+  /// See also `.isFinite`, `.isNormal`, `.isZero`, `.isReal`, `.isPure`.
   @_transparent
   public var isSubnormal: Bool {
     isFinite && !isNormal && !isZero
@@ -207,13 +165,7 @@ extension Quaternion {
   ///
   /// A quaternion is zero if the real and *all* imaginary components are zero.
   ///
-  /// See also:
-  /// -
-  /// - `.isFinite`
-  /// - `.isNormal`
-  /// - `.isSubnormal`
-  /// - `.isReal`
-  /// - `.isPure`
+  /// See also `.isFinite`, `.isNormal`, `.isSubnormal`, `.isReal`, `.isPure`.
   @_transparent
   public var isZero: Bool {
     components == .zero
@@ -223,13 +175,7 @@ extension Quaternion {
   ///
   /// A quaternion is real if *all* imaginary components are zero.
   ///
-  /// See also:
-  /// -
-  /// - `.isFinite`
-  /// - `.isNormal`
-  /// - `.isSubnormal`
-  /// - `.isZero`
-  /// - `.isPure`
+  /// See also `.isFinite`, `.isNormal`, `.isSubnormal`, `.isZero`, `.isPure`.
   @_transparent
   public var isReal: Bool {
     imaginary == .zero
@@ -239,13 +185,7 @@ extension Quaternion {
   ///
   /// A quaternion is pure if the real component is zero.
   ///
-  /// See also:
-  /// -
-  /// - `.isFinite`
-  /// - `.isNormal`
-  /// - `.isSubnormal`
-  /// - `.isZero`
-  /// - `.isReal`
+  /// See also `.isFinite`, `.isNormal`, `.isSubnormal`, `.isZero`, `.isReal`.
   @_transparent
   public var isPure: Bool {
     real.isZero
@@ -267,9 +207,7 @@ extension Quaternion {
   /// for some serialization tasks. It's also a useful implementation detail for
   /// some primitive operations.
   ///
-  /// See also:
-  /// -
-  /// - `.canonicalizedTransform`
+  /// See also `.canonicalizedTransform`.
   @_transparent
   public var canonicalized: Self {
     guard !isZero else { return .zero }
@@ -290,9 +228,7 @@ extension Quaternion {
   /// If the RealType admits non-canonical representations, the x, y, z and r
   /// components are canonicalized in the result.
   ///
-  /// See also:
-  /// -
-  /// - `.canonicalized`
+  /// See also `.canonicalized`.
   @_transparent
   public var canonicalizedTransform: Self {
     let canonical = canonicalized