Skip to content

Commit e5ed4ac

Browse files
markuswntrstephentyrone
markuswntr
authored and
stephentyrone
committed
Fix header documentation
1 parent eeff10e commit e5ed4ac

File tree

4 files changed

+38
-176
lines changed

4 files changed

+38
-176
lines changed

‎Sources/QuaternionModule/Polar.swift

Lines changed: 13 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -46,22 +46,19 @@ extension Quaternion {
4646
/// a representable result.
4747
///
4848
/// Edge cases:
49-
/// -
50-
/// If a quaternion is not finite, its `.length` is `infinity`.
49+
/// - If a quaternion is not finite, its `.length` is `infinity`.
5150
///
52-
/// See also:
53-
/// -
54-
/// - `.magnitude`
55-
/// - `.lengthSquared`
51+
/// See also `.magnitude`, `.lengthSquared`, `.polar` and
52+
/// `init(length:,phase:,axis:)`.
5653
@_transparent
5754
public var length: RealType {
5855
let naive = lengthSquared
5956
guard naive.isNormal else { return carefulLength }
6057
return .sqrt(naive)
6158
}
6259

63-
// Internal implementation detail of `length`, moving slow path off
64-
// of the inline function.
60+
// Internal implementation detail of `length`, moving slow path off
61+
// of the inline function.
6562
@usableFromInline
6663
internal var carefulLength: RealType {
6764
guard isFinite else { return .infinity }
@@ -79,10 +76,8 @@ extension Quaternion {
7976
///
8077
/// This property is more efficient to compute than `length`.
8178
///
82-
/// See also:
83-
/// -
84-
/// - `.length`
85-
/// - `.magnitude`
79+
/// See also `.magnitude`, `.length`, `.polar` and
80+
/// `init(length:,phase:,axis:)`.
8681
@_transparent
8782
public var lengthSquared: RealType {
8883
(components * components).sum()
@@ -94,23 +89,15 @@ extension Quaternion {
9489
/// and the rotation axis as SIMD3 vector of unit length.
9590
///
9691
/// Edge cases:
97-
/// -
9892
/// - If the quaternion is zero, length is `.zero` and angle and axis
9993
/// are `nan`.
10094
/// - If the quaternion is non-finite, length is `.infinity` and angle and
10195
/// axis are `nan`.
10296
/// - For any length other than `.zero` or `.infinity`, if angle is zero, axis
10397
/// is `nan`.
10498
///
105-
/// See also:
106-
/// -
107-
/// - `.angle`
108-
/// - `.axis`
109-
/// - `.angleAxis`
110-
/// - `.rotationVector`
111-
/// - `init(length:angle:axis:)`
112-
/// - `init(length:phase:axis)`
113-
/// - `init(rotation:)`
99+
/// See also `.magnitude`, `.length`, `.lengthSquared` and
100+
/// `init(length:,phase:,axis:)`.
114101
///
115102
/// [wiki]: https://en.wikipedia.org/wiki/Polar_decomposition#Quaternion_polar_decomposition
116103
public var polar: (length: RealType, phase: RealType, axis: SIMD3<RealType>) {
@@ -128,8 +115,8 @@ extension Quaternion {
128115
/// - Note: `axis` must be of unit length, or an assertion failure occurs.
129116
///
130117
/// Edge cases:
131-
/// -
132-
/// - Negative lengths are interpreted as reflecting the point through the origin, i.e.:
118+
/// - Negative lengths are interpreted as reflecting the point through the
119+
/// origin, i.e.:
133120
/// ```
134121
/// Quaternion(length: -r, phase: θ, axis: axis) == -Quaternion(length: r, phase: θ, axis: axis)
135122
/// ```
@@ -143,15 +130,7 @@ extension Quaternion {
143130
/// ```
144131
/// - Otherwise, `θ` must be finite, or a precondition failure occurs.
145132
///
146-
/// See also:
147-
/// -
148-
/// - `.angle`
149-
/// - `.axis`
150-
/// - `.angleAxis`
151-
/// - `.rotationVector`
152-
/// - `.polar`
153-
/// - `init(length:angle:axis:)`
154-
/// - `init(rotation:)`
133+
/// See also `.magnitude`, `.length`, `.lengthSquared` and `.polar`.
155134
///
156135
/// [wiki]: https://en.wikipedia.org/wiki/Polar_decomposition#Quaternion_polar_decomposition
157136
@inlinable
@@ -186,8 +165,7 @@ extension Quaternion {
186165
/// The half rotation angle in radians within *[0, π]* range.
187166
///
188167
/// Edge cases:
189-
/// -
190-
/// If the quaternion is zero or non-finite, halfAngle is `nan`.
168+
/// - If the quaternion is zero or non-finite, halfAngle is `nan`.
191169
@usableFromInline @inline(__always)
192170
internal var halfAngle: RealType {
193171
guard isFinite else { return .nan }

‎Sources/QuaternionModule/Quaternion+Numeric.swift

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -53,15 +53,11 @@ extension Quaternion: Numeric {
5353
/// properties instead.
5454
///
5555
/// Edge cases:
56-
/// -
5756
/// - If `q` is not finite, `q.magnitude` is `.infinity`.
5857
/// - If `q` is zero, `q.magnitude` is `0`.
5958
/// - Otherwise, `q.magnitude` is finite and non-zero.
6059
///
61-
/// See also:
62-
/// -
63-
/// - `.length`
64-
/// - `.lengthSquared`
60+
/// See also `.length` and `.lengthSquared`
6561
@_transparent
6662
public var magnitude: RealType {
6763
guard isFinite else { return .infinity }

‎Sources/QuaternionModule/Quaternion.swift

Lines changed: 12 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -89,55 +89,31 @@ extension Quaternion {
8989

9090
/// The quaternion with the imaginary unit **i** one, i.e. `0 + i + 0j + 0k`.
9191
///
92-
/// See also:
93-
/// -
94-
/// - .zero
95-
/// - .one
96-
/// - .j
97-
/// - .k
98-
/// - .infinity
92+
/// See also `.zero`, `.one`, `.j`, `.k` and `.infinity`.
9993
@_transparent
10094
public static var i: Quaternion {
10195
Quaternion(imaginary: SIMD3(1,0,0))
10296
}
10397

10498
/// The quaternion with the imaginary unit **j** one, i.e. `0 + 0i + j + 0k`.
10599
///
106-
/// See also:
107-
/// -
108-
/// - .zero
109-
/// - .one
110-
/// - .i
111-
/// - .k
112-
/// - .infinity
100+
/// See also `.zero`, `.one`, `.i`, `.k` and `.infinity`.
113101
@_transparent
114102
public static var j: Quaternion {
115103
Quaternion(imaginary: SIMD3(0,1,0))
116104
}
117105

118106
/// The quaternion with the imaginary unit **k** one, i.e. `0 + 0i + 0j + k`.
119107
///
120-
/// See also:
121-
/// -
122-
/// - .zero
123-
/// - .one
124-
/// - .i
125-
/// - .j
126-
/// - .infinity
108+
/// See also `.zero`, `.one`, `.i`, `.j` and `.infinity`.
127109
@_transparent
128110
public static var k: Quaternion {
129111
Quaternion(imaginary: SIMD3(0,0,1))
130112
}
131113

132114
/// The point at infinity.
133115
///
134-
/// See also:
135-
/// -
136-
/// - .zero
137-
/// - .one
138-
/// - .i
139-
/// - .j
140-
/// - .k
116+
/// See also `.zero`, `.one`, `.i`, `.j` and `.k`.
141117
@_transparent
142118
public static var infinity: Quaternion {
143119
Quaternion(.infinity)
@@ -147,13 +123,7 @@ extension Quaternion {
147123
///
148124
/// A quaternion is finite if neither component is an infinity or nan.
149125
///
150-
/// See also:
151-
/// -
152-
/// - `.isNormal`
153-
/// - `.isSubnormal`
154-
/// - `.isZero`
155-
/// - `.isReal`
156-
/// - `.isPure`
126+
/// See also `.isNormal`, `.isSubnormal`, `.isZero`, `.isReal`, `.isPure`.
157127
@_transparent
158128
public var isFinite: Bool {
159129
return components.x.isFinite
@@ -168,13 +138,7 @@ extension Quaternion {
168138
/// are normal. A floating-point number representing one of the components is normal
169139
/// if its exponent allows a full-precision representation.
170140
///
171-
/// See also:
172-
/// -
173-
/// - `.isFinite`
174-
/// - `.isSubnormal`
175-
/// - `.isZero`
176-
/// - `.isReal`
177-
/// - `.isPure`
141+
/// See also `.isFinite`, `.isSubnormal`, `.isZero`, `.isReal`, `.isPure`.
178142
@_transparent
179143
public var isNormal: Bool {
180144
return isFinite && (
@@ -191,13 +155,7 @@ extension Quaternion {
191155
/// computation is subnormal, underflow has occurred and the result generally does not have full
192156
/// precision.
193157
///
194-
/// See also:
195-
/// -
196-
/// - `.isFinite`
197-
/// - `.isNormal`
198-
/// - `.isZero`
199-
/// - `.isReal`
200-
/// - `.isPure`
158+
/// See also `.isFinite`, `.isNormal`, `.isZero`, `.isReal`, `.isPure`.
201159
@_transparent
202160
public var isSubnormal: Bool {
203161
isFinite && !isNormal && !isZero
@@ -207,13 +165,7 @@ extension Quaternion {
207165
///
208166
/// A quaternion is zero if the real and *all* imaginary components are zero.
209167
///
210-
/// See also:
211-
/// -
212-
/// - `.isFinite`
213-
/// - `.isNormal`
214-
/// - `.isSubnormal`
215-
/// - `.isReal`
216-
/// - `.isPure`
168+
/// See also `.isFinite`, `.isNormal`, `.isSubnormal`, `.isReal`, `.isPure`.
217169
@_transparent
218170
public var isZero: Bool {
219171
components == .zero
@@ -223,13 +175,7 @@ extension Quaternion {
223175
///
224176
/// A quaternion is real if *all* imaginary components are zero.
225177
///
226-
/// See also:
227-
/// -
228-
/// - `.isFinite`
229-
/// - `.isNormal`
230-
/// - `.isSubnormal`
231-
/// - `.isZero`
232-
/// - `.isPure`
178+
/// See also `.isFinite`, `.isNormal`, `.isSubnormal`, `.isZero`, `.isPure`.
233179
@_transparent
234180
public var isReal: Bool {
235181
imaginary == .zero
@@ -239,13 +185,7 @@ extension Quaternion {
239185
///
240186
/// A quaternion is pure if the real component is zero.
241187
///
242-
/// See also:
243-
/// -
244-
/// - `.isFinite`
245-
/// - `.isNormal`
246-
/// - `.isSubnormal`
247-
/// - `.isZero`
248-
/// - `.isReal`
188+
/// See also `.isFinite`, `.isNormal`, `.isSubnormal`, `.isZero`, `.isReal`.
249189
@_transparent
250190
public var isPure: Bool {
251191
real.isZero
@@ -267,9 +207,7 @@ extension Quaternion {
267207
/// for some serialization tasks. It's also a useful implementation detail for
268208
/// some primitive operations.
269209
///
270-
/// See also:
271-
/// -
272-
/// - `.canonicalizedTransform`
210+
/// See also `.canonicalizedTransform`.
273211
@_transparent
274212
public var canonicalized: Self {
275213
guard !isZero else { return .zero }
@@ -290,9 +228,7 @@ extension Quaternion {
290228
/// If the RealType admits non-canonical representations, the x, y, z and r
291229
/// components are canonicalized in the result.
292230
///
293-
/// See also:
294-
/// -
295-
/// - `.canonicalized`
231+
/// See also `.canonicalized`.
296232
@_transparent
297233
public var canonicalizedTransform: Self {
298234
let canonical = canonicalized

0 commit comments

Comments
 (0)