Skip to content

Commit f19efad

Browse files
regexidentregexident
committed
Improved documentation of Surge-provided assert functions
1 parent f0b34e0 commit f19efad

File tree

1 file changed

+56
-38
lines changed

1 file changed

+56
-38
lines changed

‎Tests/SurgeTests/XCTAssert+Surge.swift

Lines changed: 56 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -142,26 +142,24 @@ private func fail(
142142
XCTFail(message, file: file, line: line)
143143
}
144144

145-
/// Allows comparing:
145+
/// Asserts that two values are equal within a certain accuracy.
146146
///
147-
/// ```
148-
/// T where
149-
/// T: Collection,
150-
/// T.Element == U,
151-
/// U: FloatingPoint
152-
/// ```
153-
///
154-
/// Useful for comparing:
155-
/// - `[Float]`
156-
/// - `[Double]`
157-
func XCTAssertEqual<T, U>(
147+
/// - Parameters:
148+
/// - expression1: An expression of type `T: Collection`, where `T.Element` conforms `FloatingPoint`.
149+
/// - expression2: An expression of type `T: Collection`, where `T.Element` conforms `FloatingPoint`.
150+
/// - accuracy: An expression of type `T.Element`, where `T.Element` conforms to `FloatingPoint`.
151+
/// Describes the maximum difference between `expression1` and `expression2` for these values to be considered equal.
152+
/// - message: An optional description of the failure.
153+
/// - file: The file in which failure occurred. Defaults to the file name of the test case in which this function was called.
154+
/// - line: The line number on which failure occurred. Defaults to the line number on which this function was called.
155+
func XCTAssertEqual<T>(
158156
_ expression1: @autoclosure () throws -> T,
159157
_ expression2: @autoclosure () throws -> T,
160-
accuracy: U? = nil,
158+
accuracy: T.Element? = nil,
161159
_ message: @autoclosure () -> String = "",
162160
file: StaticString = #file,
163161
line: UInt = #line
164-
) where T: Collection, T.Element == U, U: FloatingPoint & ExpressibleByFloatLiteral {
162+
) where T: Collection, T.Element: FloatingPoint & ExpressibleByFloatLiteral {
165163
XCTAssertEqual1D(
166164
try expression1(),
167165
try expression2(),
@@ -172,14 +170,27 @@ func XCTAssertEqual<T, U>(
172170
)
173171
}
174172

175-
func XCTAssertEqual1D<T, U>(
173+
/// Asserts that two values are equal within a certain accuracy.
174+
///
175+
/// Semantically the same as its `XCTAssertEqual<T>(_:_:accuracy:_:file:line:)` counterpart
176+
/// (i.e. without the `…1D` suffix), but with improved error messages.
177+
///
178+
/// - Parameters:
179+
/// - expression1: An expression of type `T: Collection`, where `T.Element` conforms `FloatingPoint`.
180+
/// - expression2: An expression of type `T: Collection`, where `T.Element` conforms `FloatingPoint`.
181+
/// - accuracy: An expression of type `T.Element`, where `T.Element` conforms to `FloatingPoint`.
182+
/// Describes the maximum difference between `expression1` and `expression2` for these values to be considered equal.
183+
/// - message: An optional description of the failure.
184+
/// - file: The file in which failure occurred. Defaults to the file name of the test case in which this function was called.
185+
/// - line: The line number on which failure occurred. Defaults to the line number on which this function was called.
186+
func XCTAssertEqual1D<T>(
176187
_ expression1: @autoclosure () throws -> T,
177188
_ expression2: @autoclosure () throws -> T,
178-
accuracy: U? = nil,
189+
accuracy: T.Element? = nil,
179190
_ message: @autoclosure () -> String = "",
180191
file: StaticString = #file,
181192
line: UInt = #line
182-
) where T: Collection, T.Element == U, U: FloatingPoint & ExpressibleByFloatLiteral {
193+
) where T: Collection, T.Element: FloatingPoint & ExpressibleByFloatLiteral {
183194
let prefix: Prefix = (accuracy == nil) ? .assertEqual : .assertEqualWithAccuracy
184195

185196
let (actual, expected): (T, T)
@@ -200,30 +211,24 @@ func XCTAssertEqual1D<T, U>(
200211
return fail(prefix: prefix, failureMessage: error.description, file: file, line: line)
201212
}
202213

203-
/// Allows comparing:
214+
/// Asserts that two values are equal within a certain accuracy.
204215
///
205-
/// ```
206-
/// T where
207-
/// T: Collection,
208-
/// U: Collection,
209-
/// T.Element == U,
210-
/// U.Element == V,
211-
/// V: FloatingPoint
212-
/// ```
213-
///
214-
/// Useful for comparing:
215-
/// - `[[Float]]`
216-
/// - `[[Double]]`
217-
/// - `Matrix<Float>`
218-
/// - `Matrix<Double>`
219-
func XCTAssertEqual<T, U, V>(
216+
/// - Parameters:
217+
/// - expression1: An expression of type `T: Collection`, `T.Element == U`, where `U` is `FloatingPoint`.
218+
/// - expression2: An expression of type `T: Collection`, `T.Element == U`, where `U` is `FloatingPoint`.
219+
/// - accuracy: An expression of type `U.Element`, where `U.Element` conforms to `FloatingPoint`.
220+
/// Describes the maximum difference between `expression1` and `expression2` for these values to be considered equal.
221+
/// - message: An optional description of the failure.
222+
/// - file: The file in which failure occurred. Defaults to the file name of the test case in which this function was called.
223+
/// - line: The line number on which failure occurred. Defaults to the line number on which this function was called.
224+
func XCTAssertEqual<T, U>(
220225
_ expression1: @autoclosure () throws -> T,
221226
_ expression2: @autoclosure () throws -> T,
222-
accuracy: V? = nil,
227+
accuracy: U.Element? = nil,
223228
_ message: @autoclosure () -> String = "",
224229
file: StaticString = #file,
225230
line: UInt = #line
226-
) where T: Collection, U: Collection, T.Element == U, U.Element == V, V: FloatingPoint & ExpressibleByFloatLiteral {
231+
) where T: Collection, U: Collection, T.Element == U, U.Element: FloatingPoint & ExpressibleByFloatLiteral {
227232
XCTAssertEqual2D(
228233
try expression1(),
229234
try expression2(),
@@ -234,14 +239,27 @@ func XCTAssertEqual<T, U, V>(
234239
)
235240
}
236241

237-
func XCTAssertEqual2D<T, U, V>(
242+
/// Asserts that two values are equal within a certain accuracy.
243+
///
244+
/// Semantically the same as its `XCTAssertEqual<T>(_:_:accuracy:_:file:line:)` counterpart
245+
/// (i.e. without the `…2D` suffix), but with improved error messages.
246+
///
247+
/// - Parameters:
248+
/// - expression1: An expression of type `T: Collection`, `T.Element == U`, where `U` is `FloatingPoint`.
249+
/// - expression2: An expression of type `T: Collection`, `T.Element == U`, where `U` is `FloatingPoint`.
250+
/// - accuracy: An expression of type `U.Element`, where `U.Element` conforms to `FloatingPoint`.
251+
/// Describes the maximum difference between `expression1` and `expression2` for these values to be considered equal.
252+
/// - message: An optional description of the failure.
253+
/// - file: The file in which failure occurred. Defaults to the file name of the test case in which this function was called.
254+
/// - line: The line number on which failure occurred. Defaults to the line number on which this function was called.
255+
func XCTAssertEqual2D<T, U>(
238256
_ expression1: @autoclosure () throws -> T,
239257
_ expression2: @autoclosure () throws -> T,
240-
accuracy: V? = nil,
258+
accuracy: U.Element? = nil,
241259
_ message: @autoclosure () -> String = "",
242260
file: StaticString = #file,
243261
line: UInt = #line
244-
) where T: Collection, U: Collection, T.Element == U, U.Element == V, V: FloatingPoint & ExpressibleByFloatLiteral {
262+
) where T: Collection, U: Collection, T.Element == U, U.Element: FloatingPoint & ExpressibleByFloatLiteral {
245263
let prefix: Prefix = (accuracy == nil) ? .assertEqual : .assertEqualWithAccuracy
246264

247265
let (actual, expected): (T, T)

0 commit comments

Comments
 (0)