From f19efad1534e634c4895bc001024354785296fc9 Mon Sep 17 00:00:00 2001 From: Vincent Esche Date: Thu, 29 Aug 2019 23:56:47 +0200 Subject: [PATCH] Improved documentation of Surge-provided assert functions --- Tests/SurgeTests/XCTAssert+Surge.swift | 94 +++++++++++++++----------- 1 file changed, 56 insertions(+), 38 deletions(-) diff --git a/Tests/SurgeTests/XCTAssert+Surge.swift b/Tests/SurgeTests/XCTAssert+Surge.swift index 6763532..1eeb8ac 100644 --- a/Tests/SurgeTests/XCTAssert+Surge.swift +++ b/Tests/SurgeTests/XCTAssert+Surge.swift @@ -142,26 +142,24 @@ private func fail( XCTFail(message, file: file, line: line) } -/// Allows comparing: +/// Asserts that two values are equal within a certain accuracy. /// -/// ``` -/// T where -/// T: Collection, -/// T.Element == U, -/// U: FloatingPoint -/// ``` -/// -/// Useful for comparing: -/// - `[Float]` -/// - `[Double]` -func XCTAssertEqual( +/// - Parameters: +/// - expression1: An expression of type `T: Collection`, where `T.Element` conforms `FloatingPoint`. +/// - expression2: An expression of type `T: Collection`, where `T.Element` conforms `FloatingPoint`. +/// - accuracy: An expression of type `T.Element`, where `T.Element` conforms to `FloatingPoint`. +/// Describes the maximum difference between `expression1` and `expression2` for these values to be considered equal. +/// - message: An optional description of the failure. +/// - file: The file in which failure occurred. Defaults to the file name of the test case in which this function was called. +/// - line: The line number on which failure occurred. Defaults to the line number on which this function was called. +func XCTAssertEqual( _ expression1: @autoclosure () throws -> T, _ expression2: @autoclosure () throws -> T, - accuracy: U? = nil, + accuracy: T.Element? = nil, _ message: @autoclosure () -> String = "", file: StaticString = #file, line: UInt = #line -) where T: Collection, T.Element == U, U: FloatingPoint & ExpressibleByFloatLiteral { +) where T: Collection, T.Element: FloatingPoint & ExpressibleByFloatLiteral { XCTAssertEqual1D( try expression1(), try expression2(), @@ -172,14 +170,27 @@ func XCTAssertEqual( ) } -func XCTAssertEqual1D( +/// Asserts that two values are equal within a certain accuracy. +/// +/// Semantically the same as its `XCTAssertEqual(_:_:accuracy:_:file:line:)` counterpart +/// (i.e. without the `…1D` suffix), but with improved error messages. +/// +/// - Parameters: +/// - expression1: An expression of type `T: Collection`, where `T.Element` conforms `FloatingPoint`. +/// - expression2: An expression of type `T: Collection`, where `T.Element` conforms `FloatingPoint`. +/// - accuracy: An expression of type `T.Element`, where `T.Element` conforms to `FloatingPoint`. +/// Describes the maximum difference between `expression1` and `expression2` for these values to be considered equal. +/// - message: An optional description of the failure. +/// - file: The file in which failure occurred. Defaults to the file name of the test case in which this function was called. +/// - line: The line number on which failure occurred. Defaults to the line number on which this function was called. +func XCTAssertEqual1D( _ expression1: @autoclosure () throws -> T, _ expression2: @autoclosure () throws -> T, - accuracy: U? = nil, + accuracy: T.Element? = nil, _ message: @autoclosure () -> String = "", file: StaticString = #file, line: UInt = #line -) where T: Collection, T.Element == U, U: FloatingPoint & ExpressibleByFloatLiteral { +) where T: Collection, T.Element: FloatingPoint & ExpressibleByFloatLiteral { let prefix: Prefix = (accuracy == nil) ? .assertEqual : .assertEqualWithAccuracy let (actual, expected): (T, T) @@ -200,30 +211,24 @@ func XCTAssertEqual1D( return fail(prefix: prefix, failureMessage: error.description, file: file, line: line) } -/// Allows comparing: +/// Asserts that two values are equal within a certain accuracy. /// -/// ``` -/// T where -/// T: Collection, -/// U: Collection, -/// T.Element == U, -/// U.Element == V, -/// V: FloatingPoint -/// ``` -/// -/// Useful for comparing: -/// - `[[Float]]` -/// - `[[Double]]` -/// - `Matrix` -/// - `Matrix` -func XCTAssertEqual( +/// - Parameters: +/// - expression1: An expression of type `T: Collection`, `T.Element == U`, where `U` is `FloatingPoint`. +/// - expression2: An expression of type `T: Collection`, `T.Element == U`, where `U` is `FloatingPoint`. +/// - accuracy: An expression of type `U.Element`, where `U.Element` conforms to `FloatingPoint`. +/// Describes the maximum difference between `expression1` and `expression2` for these values to be considered equal. +/// - message: An optional description of the failure. +/// - file: The file in which failure occurred. Defaults to the file name of the test case in which this function was called. +/// - line: The line number on which failure occurred. Defaults to the line number on which this function was called. +func XCTAssertEqual( _ expression1: @autoclosure () throws -> T, _ expression2: @autoclosure () throws -> T, - accuracy: V? = nil, + accuracy: U.Element? = nil, _ message: @autoclosure () -> String = "", file: StaticString = #file, line: UInt = #line -) where T: Collection, U: Collection, T.Element == U, U.Element == V, V: FloatingPoint & ExpressibleByFloatLiteral { +) where T: Collection, U: Collection, T.Element == U, U.Element: FloatingPoint & ExpressibleByFloatLiteral { XCTAssertEqual2D( try expression1(), try expression2(), @@ -234,14 +239,27 @@ func XCTAssertEqual( ) } -func XCTAssertEqual2D( +/// Asserts that two values are equal within a certain accuracy. +/// +/// Semantically the same as its `XCTAssertEqual(_:_:accuracy:_:file:line:)` counterpart +/// (i.e. without the `…2D` suffix), but with improved error messages. +/// +/// - Parameters: +/// - expression1: An expression of type `T: Collection`, `T.Element == U`, where `U` is `FloatingPoint`. +/// - expression2: An expression of type `T: Collection`, `T.Element == U`, where `U` is `FloatingPoint`. +/// - accuracy: An expression of type `U.Element`, where `U.Element` conforms to `FloatingPoint`. +/// Describes the maximum difference between `expression1` and `expression2` for these values to be considered equal. +/// - message: An optional description of the failure. +/// - file: The file in which failure occurred. Defaults to the file name of the test case in which this function was called. +/// - line: The line number on which failure occurred. Defaults to the line number on which this function was called. +func XCTAssertEqual2D( _ expression1: @autoclosure () throws -> T, _ expression2: @autoclosure () throws -> T, - accuracy: V? = nil, + accuracy: U.Element? = nil, _ message: @autoclosure () -> String = "", file: StaticString = #file, line: UInt = #line -) where T: Collection, U: Collection, T.Element == U, U.Element == V, V: FloatingPoint & ExpressibleByFloatLiteral { +) where T: Collection, U: Collection, T.Element == U, U.Element: FloatingPoint & ExpressibleByFloatLiteral { let prefix: Prefix = (accuracy == nil) ? .assertEqual : .assertEqualWithAccuracy let (actual, expected): (T, T)