From 1eda890211097c46ea06808cbe883450aa012c3b Mon Sep 17 00:00:00 2001 From: Daniel Saidi Date: Sun, 22 Sep 2024 20:24:56 +0200 Subject: [PATCH] Update docs --- Sources/MockingKit/AsyncMockReference.swift | 10 +- Sources/MockingKit/Mock.swift | 18 +-- Sources/MockingKit/MockCall.swift | 16 +- Sources/MockingKit/MockReference.swift | 10 +- Sources/MockingKit/Mockable+Call.swift | 130 ++++++---------- Sources/MockingKit/Mockable+Inspect.swift | 146 ++++++++---------- Sources/MockingKit/Mockable+Register.swift | 44 ++---- Sources/MockingKit/Mockable+Reset.swift | 44 ++---- Sources/MockingKit/Mockable.swift | 31 ++-- .../Mocks/MockNotificationCenter.swift | 4 +- Sources/MockingKit/Mocks/MockPasteboard.swift | 10 +- .../Mocks/MockTextDocumentProxy.swift | 11 +- .../MockingKit/Mocks/MockUserDefaults.swift | 4 +- 13 files changed, 191 insertions(+), 287 deletions(-) diff --git a/Sources/MockingKit/AsyncMockReference.swift b/Sources/MockingKit/AsyncMockReference.swift index 5daca6a..1968cdf 100644 --- a/Sources/MockingKit/AsyncMockReference.swift +++ b/Sources/MockingKit/AsyncMockReference.swift @@ -8,12 +8,10 @@ import Foundation -/** - This struct can be used to create async function references. - - Mock function references get unique IDs, which means that a - mock reference instance can be uniquely identifier. - */ +/// This type can be used to create mock function references. +/// +/// Function references get unique IDs, which means that the +/// mock reference instance can be uniquely identified. public struct AsyncMockReference: Identifiable { public init(_ function: @escaping (Arguments) async throws -> Result) { diff --git a/Sources/MockingKit/Mock.swift b/Sources/MockingKit/Mock.swift index a5bccdf..3a9e849 100644 --- a/Sources/MockingKit/Mock.swift +++ b/Sources/MockingKit/Mock.swift @@ -8,16 +8,14 @@ import Foundation -/** - This class can be inherited when creating a mock class that - doesn't have to inherit another class. - - The class implements the ``Mockable`` protocol by returning - self as the ``mock`` property value. - - Inherit the class instead of implementing ``Mockable`` when - possible. It saves you a little code for each mock you make. - */ +/// This class can be inherited when you want to create mock +/// classes that don't have to inherit any other classes. +/// +/// The class implements ``Mockable`` by returning `self` as +/// the ``mock`` property. +/// +/// Inherit this type instead of implementing the ``Mockable`` +/// protocol, to save some code for every mock you create. open class Mock: Mockable { public init() {} diff --git a/Sources/MockingKit/MockCall.swift b/Sources/MockingKit/MockCall.swift index 8b19ef3..3dd2eac 100644 --- a/Sources/MockingKit/MockCall.swift +++ b/Sources/MockingKit/MockCall.swift @@ -8,20 +8,16 @@ import Foundation -/** - This struct represents a "recorded" mock function call with - information about the provided ``arguments`` and ``result``. - - A function that doesn't return anything has a `Void` result. -*/ +/// This struct represents function calls, with the provided +/// ``arguments`` and the returned ``result``. +/// +/// Function that don't return anything have a `Void` result. public struct MockCall: AnyCall { public let arguments: Arguments public let result: Result? } -/** - This protocol represents any kind of mock function call. It - is used to type erase the generic `MockCall`. - */ +/// This protocol represents any kind of mock function call. +/// It's used to type erase the generic `MockCall`. public protocol AnyCall {} diff --git a/Sources/MockingKit/MockReference.swift b/Sources/MockingKit/MockReference.swift index b506d72..79f5549 100644 --- a/Sources/MockingKit/MockReference.swift +++ b/Sources/MockingKit/MockReference.swift @@ -8,12 +8,10 @@ import Foundation -/** - This struct can be used to create a mock function reference. - - Mock function references get unique IDs, which means that a - mock reference instance can be uniquely identifier. - */ +/// This type can be used to create mock function references. +/// +/// Function references get unique IDs, which means that the +/// mock reference instance can be uniquely identified. public struct MockReference: Identifiable { public init(_ function: @escaping (Arguments) throws -> Result) { diff --git a/Sources/MockingKit/Mockable+Call.swift b/Sources/MockingKit/Mockable+Call.swift index 99da969..fd13ec3 100644 --- a/Sources/MockingKit/Mockable+Call.swift +++ b/Sources/MockingKit/Mockable+Call.swift @@ -10,19 +10,14 @@ import Foundation public extension Mockable { - /** - Call a mock reference with `non-optional` result. - - This will return any pre-registered result, or crash if - no result has been registered. - - Note that this function should only be used by the mock - itself and not called from the outside. - - - Parameters: - - ref: The mock reference to call. - - args: The arguments to call the functions with. - */ + /// Call a mock reference with a `non-optional` result. + /// + /// This will return any pre-registered result, or crash + /// if no result has been registered. + /// + /// - Parameters: + /// - ref: The mock reference to call. + /// - args: The arguments to call the functions with. func call( _ ref: MockReference, args: Arguments, @@ -46,19 +41,14 @@ public extension Mockable { return result } - /** - Call an async mock reference with `non-optional` result. - - This will return any pre-registered result, or crash if - no result has been registered. - - Note that this function should only be used by the mock - itself and not called from the outside. - - - Parameters: - - ref: The mock reference to call. - - args: The arguments to call the functions with. - */ + /// Call a mock reference with a `non-optional` result. + /// + /// This will return any pre-registered result, or crash + /// if no result has been registered. + /// + /// - Parameters: + /// - ref: The mock reference to call. + /// - args: The arguments to call the functions with. func call( _ ref: AsyncMockReference, args: Arguments, @@ -82,20 +72,15 @@ public extension Mockable { return result } - /** - Call a mock reference with `non-optional` result. - - This will return a pre-registered result or a `fallback` - value if no result has been registered. - - Note that this function should only be used by the mock - itself and not called from the outside. - - - Parameters: - - ref: The mock reference to call. - - args: The arguments to call the functions with. - - fallback: The value to return if no result has been registered. - */ + /// Call a mock reference with a `non-optional` result. + /// + /// This will return any pre-registered result or return + /// a `fallback` value if no result has been registered. + /// + /// - Parameters: + /// - ref: The mock reference to call. + /// - args: The arguments to call the functions with. + /// - fallback: The value to return if no result has been registered. func call( _ ref: MockReference, args: Arguments, @@ -106,20 +91,15 @@ public extension Mockable { return result } - /** - Call an async mock reference with `non-optional` result. - - This will return a pre-registered result or a `fallback` - value if no result has been registered. - - Note that this function should only be used by the mock - itself and not called from the outside. - - - Parameters: - - ref: The mock reference to call. - - args: The arguments to call the functions with. - - fallback: The value to return if no result has been registered. - */ + /// Call a mock reference with a `non-optional` result. + /// + /// This will return any pre-registered result or return + /// a `fallback` value if no result has been registered. + /// + /// - Parameters: + /// - ref: The mock reference to call. + /// - args: The arguments to call the functions with. + /// - fallback: The value to return if no result has been registered. func call( _ ref: AsyncMockReference, args: Arguments, @@ -130,19 +110,14 @@ public extension Mockable { return result } - /** - Call a mock reference with `optional` result. - - This will return a pre-registered result or `nil` if no - result has been registered. - - Note that this function should only be used by the mock - itself and not called from the outside. - - - Parameters: - - ref: The mock reference to call. - - args: The arguments to call the functions with. - */ + /// Call a mock reference with an `optional` result. + /// + /// This will return a pre-registered result or `nil` if + /// no result has been registered. + /// + /// - Parameters: + /// - ref: The mock reference to call. + /// - args: The arguments to call the functions with. func call( _ ref: MockReference, args: Arguments @@ -152,19 +127,14 @@ public extension Mockable { return result } - /** - Call an async mock reference with `optional` result. - - This will return a pre-registered result or `nil` if no - result has been registered. - - Note that this function should only be used by the mock - itself and not called from the outside. - - - Parameters: - - ref: The mock reference to call. - - args: The arguments to call the functions with. - */ + /// Call a mock reference with an `optional` result. + /// + /// This will return a pre-registered result or `nil` if + /// no result has been registered. + /// + /// - Parameters: + /// - ref: The mock reference to call. + /// - args: The arguments to call the functions with. func call( _ ref: AsyncMockReference, args: Arguments diff --git a/Sources/MockingKit/Mockable+Inspect.swift b/Sources/MockingKit/Mockable+Inspect.swift index 8aa7c9c..fcb9ef0 100644 --- a/Sources/MockingKit/Mockable+Inspect.swift +++ b/Sources/MockingKit/Mockable+Inspect.swift @@ -10,111 +10,94 @@ import Foundation public extension Mockable { - /** - Get all calls to a certain mock reference. - - - Parameters: - - ref: The mock reference to check calls for. - */ + /// Get all calls to a certain mock reference. + /// + /// - Parameters: + /// - ref: The mock reference to check calls for. func calls( to ref: MockReference ) -> [MockCall] { registeredCalls(for: ref) } - /** - Get all calls to a certain mock reference. - - - Parameters: - - refKeyPath: A key path to the mock reference to check calls for. - */ + /// Get all calls to a certain mock reference. + /// + /// - Parameters: + /// - refKeyPath: A key path to the mock reference to check calls for. func calls( to refKeyPath: KeyPath> ) -> [MockCall] { calls(to: self[keyPath: refKeyPath]) } - /** - Get all calls to a certain async mock reference. - - - Parameters: - - ref: The mock reference to check calls for. - */ + /// Get all calls to a certain async mock reference. + /// + /// - Parameters: + /// - ref: The mock reference to check calls for. func calls( to ref: AsyncMockReference ) -> [MockCall] { registeredCalls(for: ref) } - /** - Get all calls to a certain async mock reference. - - - Parameters: - - refKeyPath: A key path to the mock reference to check calls for. - */ + /// Get all calls to a certain async mock reference. + /// + /// - Parameters: + /// - refKeyPath: A key path to the mock reference to check calls for. func calls( to refKeyPath: KeyPath> ) -> [MockCall] { calls(to: self[keyPath: refKeyPath]) } - /** - Check if a mock reference has been called. - - - Parameters: - - ref: The mock reference to check calls for. - */ + /// Check if a mock reference has been called. + /// + /// - Parameters: + /// - ref: The mock reference to check calls for. func hasCalled( _ ref: MockReference ) -> Bool { calls(to: ref).count > 0 } - /** - Check if a mock reference has been called. - - - Parameters: - - refKeyPath: A key path to the mock reference to check calls for. - */ + /// Check if a mock reference has been called. + /// + /// - Parameters: + /// - refKeyPath: A key path to the mock reference to check calls for. func hasCalled( _ refKeyPath: KeyPath> ) -> Bool { hasCalled(self[keyPath: refKeyPath]) } - /** - Check if an async mock reference has been called. - - - Parameters: - - ref: The mock reference to check calls for. - */ + /// Check if an async mock reference has been called. + /// + /// - Parameters: + /// - ref: The mock reference to check calls for. func hasCalled( _ ref: AsyncMockReference ) -> Bool { calls(to: ref).count > 0 } - /** - Check if an async mock reference has been called. - - - Parameters: - - refKeyPath: A key path to the mock reference to check calls for. - */ + /// Check if an async mock reference has been called. + /// + /// - Parameters: + /// - refKeyPath: A key path to the mock reference to check calls for. func hasCalled( _ refKeyPath: KeyPath> ) -> Bool { hasCalled(self[keyPath: refKeyPath]) } - /** - Check if a mock reference has been called. - - For this to return true the actual number of calls must - match the provided `numberOfCalls`. - - - Parameters: - - ref: The mock reference to check calls for. - */ + /// Check if a mock reference has been called. + /// + /// For this function to return `true` the actual number + /// of calls must match the provided `numberOfCalls`. + /// + /// - Parameters: + /// - ref: The mock reference to check calls for. + /// - numberOfTimes: The expected number of calls. func hasCalled( _ ref: MockReference, numberOfTimes: Int @@ -122,15 +105,14 @@ public extension Mockable { calls(to: ref).count == numberOfTimes } - /** - Check if a mock reference has been called. - - For this to return true the actual number of calls must - match the provided `numberOfCalls`. - - - Parameters: - - refKeyPath: A key path to the mock reference to check calls for. - */ + /// Check if a mock reference has been called. + /// + /// For this function to return `true` the actual number + /// of calls must match the provided `numberOfCalls`. + /// + /// - Parameters: + /// - refKeyPath: A key path to the mock reference to check calls for. + /// - numberOfTimes: The expected number of calls. func hasCalled( _ refKeyPath: KeyPath>, numberOfTimes: Int @@ -138,15 +120,13 @@ public extension Mockable { hasCalled(self[keyPath: refKeyPath], numberOfTimes: numberOfTimes) } - /** - Check if an async mock reference has been called. - - For this to return true the actual number of calls must - match the provided `numberOfCalls`. - - - Parameters: - - ref: The mock reference to check calls for. - */ + /// Check if an async mock reference has been called. + /// + /// For this function to return `true` the actual number + /// of calls must match the provided `numberOfCalls`. + /// + /// - Parameters: + /// - ref: The mock reference to check calls for. func hasCalled( _ ref: AsyncMockReference, numberOfTimes: Int @@ -154,15 +134,13 @@ public extension Mockable { calls(to: ref).count == numberOfTimes } - /** - Check if an async mock reference has been called. - - For this to return true the actual number of calls must - match the provided `numberOfCalls`. - - - Parameters: - - refKeyPath: A key path to the mock reference to check calls for. - */ + /// Check if an async mock reference has been called. + /// + /// For this function to return `true` the actual number + /// of calls must match the provided `numberOfCalls`. + /// + /// - Parameters: + /// - refKeyPath: A key path to the mock reference to check calls for. func hasCalled( _ refKeyPath: KeyPath>, numberOfTimes: Int diff --git a/Sources/MockingKit/Mockable+Register.swift b/Sources/MockingKit/Mockable+Register.swift index f73c150..7ac2652 100644 --- a/Sources/MockingKit/Mockable+Register.swift +++ b/Sources/MockingKit/Mockable+Register.swift @@ -10,13 +10,10 @@ import Foundation public extension Mockable { - /** - Register a result value for a mock reference. - - - Parameters: - - ref: The mock reference to register a result for. - - result: What to return when the function is called. - */ + /// Register a result value for a mock reference. + /// - Parameters: + /// - ref: The mock reference to register a result for. + /// - result: What to return when the function is called. func registerResult( for ref: MockReference, result: @escaping (Arguments) throws -> Result @@ -24,13 +21,10 @@ public extension Mockable { mock.registeredResults[ref.id] = result } - /** - Register a result value for a mock reference. - - - Parameters: - - refKeyPath: A key path to the mock reference to register a result for. - - result: What to return when the function is called. - */ + /// Register a result value for a mock reference. + /// - Parameters: + /// - refKeyPath: A key path to the mock reference to register a result for. + /// - result: What to return when the function is called. func registerResult( for refKeyPath: KeyPath>, result: @escaping (Arguments) throws -> Result @@ -38,13 +32,10 @@ public extension Mockable { registerResult(for: self[keyPath: refKeyPath], result: result) } - /** - Register a result value for an async mock reference. - - - Parameters: - - ref: The mock reference to register a result for. - - result: What to return when the function is called. - */ + /// Register a result value for an async mock reference. + /// - Parameters: + /// - ref: The mock reference to register a result for. + /// - result: What to return when the function is called. func registerResult( for ref: AsyncMockReference, result: @escaping (Arguments) async throws -> Result @@ -52,13 +43,10 @@ public extension Mockable { mock.registeredResults[ref.id] = result } - /** - Register a result value for an async mock reference. - - - Parameters: - - refKeyPath: A key path to the mock reference to register a result for. - - result: What to return when the function is called. - */ + /// Register a result value for an async mock reference. + /// - Parameters: + /// - refKeyPath: A key path to the mock reference to register a result for. + /// - result: What to return when the function is called. func registerResult( for refKeyPath: KeyPath>, result: @escaping (Arguments) async throws -> Result diff --git a/Sources/MockingKit/Mockable+Reset.swift b/Sources/MockingKit/Mockable+Reset.swift index 9e35fec..1af6e54 100644 --- a/Sources/MockingKit/Mockable+Reset.swift +++ b/Sources/MockingKit/Mockable+Reset.swift @@ -10,55 +10,45 @@ import Foundation public extension Mockable { - /** - Reset all registered calls. - */ + /// Reset all registered calls. func resetCalls() { mock.registeredCalls = [:] } - /** - Reset all registered calls for a mock reference. - - - Parameters: - - ref: The mock reference to reset any calls for. - */ + /// Reset all registered calls for a mock reference. + /// + /// - Parameters: + /// - ref: The mock reference to reset any calls for. func resetCalls( to ref: MockReference ) { mock.registeredCalls[ref.id] = [] } - /** - Reset all registered calls for a mock reference. - - - Parameters: - - refKeyPath: A key path to the mock reference to reset any calls for. - */ + /// Reset all registered calls for a mock reference. + /// + /// - Parameters: + /// - refKeyPath: A key path to the mock reference to reset any calls for. func resetCalls( to refKeyPath: KeyPath> ) { resetCalls(to: self[keyPath: refKeyPath]) } - /** - Reset all registered calls for an async mock reference. - - - Parameters: - - ref: The mock reference to reset any calls for. - */ + /// Reset all registered calls for a mock reference. + /// + /// - Parameters: + /// - ref: The mock reference to reset any calls for. func resetCalls( to ref: AsyncMockReference ) { mock.registeredCalls[ref.id] = [] } - /** - Reset all registered calls for an async mock reference. - - - Parameters: - - refKeyPath: A key path to the mock reference to reset any calls for. - */ + /// Reset all registered calls for a mock reference. + /// + /// - Parameters: + /// - refKeyPath: A key path to the mock reference to reset any calls for. func resetCalls( to refKeyPath: KeyPath> ) { diff --git a/Sources/MockingKit/Mockable.swift b/Sources/MockingKit/Mockable.swift index 02355e5..845d3d9 100644 --- a/Sources/MockingKit/Mockable.swift +++ b/Sources/MockingKit/Mockable.swift @@ -8,23 +8,20 @@ import Foundation -/** - This protocol can be implemented when creating a mock class - that has to inherit another class. - - To implement this protocol, just inherit the base class and - this protocol, then provide a ``mock`` property: - - ``` - class MyMock: BaseClass, Mockable { - - let mock = Mock() - } - ``` - - Inherit ``Mock`` instead of implementing this protocol when - possible. It saves you a little code for each mock you make. -*/ +/// This class can be inherited when you want to create mock +/// classes that have to inherit other classes. +/// +/// To implement this protocol, just inherit your base class +/// and provide a ``mock`` property: +/// +/// ``` +/// class MyMock: BaseClass, Mockable { +/// let mock = Mock() +/// } +/// ``` +/// +/// Implement this protocol instead of inheriting the ``Mock`` +/// base class, to save some code for every mock you create. public protocol Mockable { typealias Function = Any diff --git a/Sources/MockingKit/Mocks/MockNotificationCenter.swift b/Sources/MockingKit/Mocks/MockNotificationCenter.swift index 5d01405..2b8fcd7 100644 --- a/Sources/MockingKit/Mocks/MockNotificationCenter.swift +++ b/Sources/MockingKit/Mocks/MockNotificationCenter.swift @@ -8,9 +8,7 @@ import Foundation -/** - This class can be used to mock `NotificationCenter`. - */ +/// This class can be used to mock `NotificationCenter`. open class MockNotificationCenter: NotificationCenter, Mockable { public lazy var addObserverForNameRef = MockReference(mockAddObserverForName) diff --git a/Sources/MockingKit/Mocks/MockPasteboard.swift b/Sources/MockingKit/Mocks/MockPasteboard.swift index 28a6bf2..2374aa1 100644 --- a/Sources/MockingKit/Mocks/MockPasteboard.swift +++ b/Sources/MockingKit/Mocks/MockPasteboard.swift @@ -9,12 +9,10 @@ #if os(iOS) import UIKit -/** - This class can be used to mock `UIPasteboard`. - - The mock only mocks `setData(_:forPasteboardType:)` for now, - but you can subclass this class and mock more functionality. - */ +/// This class can be used to mock `UIPasteboard`. +/// +/// This mock only mocks `setData(_:forPasteboardType:)` for +/// now, but you can subclass it and mock more functionality. open class MockPasteboard: UIPasteboard, Mockable { public lazy var setDataRef = MockReference(setData) diff --git a/Sources/MockingKit/Mocks/MockTextDocumentProxy.swift b/Sources/MockingKit/Mocks/MockTextDocumentProxy.swift index b89d4dd..ef1d407 100644 --- a/Sources/MockingKit/Mocks/MockTextDocumentProxy.swift +++ b/Sources/MockingKit/Mocks/MockTextDocumentProxy.swift @@ -9,13 +9,10 @@ #if os(iOS) import UIKit -/** - This class can be used to mock `UITextDocumentProxy`. - - This class mocks many functions, but not all. If you miss a - certain function, you can subclass this class and mock more - functionality in the subclass. - */ +/// This class can be used to mock `UITextDocumentProxy`. +/// +/// This class mocks many functions, but not everything. You +/// can subclass it and mock more functions in your subclass. open class MockTextDocumentProxy: NSObject, UITextDocumentProxy, Mockable { public lazy var adjustTextPositionRef = MockReference(adjustTextPosition) diff --git a/Sources/MockingKit/Mocks/MockUserDefaults.swift b/Sources/MockingKit/Mocks/MockUserDefaults.swift index 4488238..d4c8fd2 100644 --- a/Sources/MockingKit/Mocks/MockUserDefaults.swift +++ b/Sources/MockingKit/Mocks/MockUserDefaults.swift @@ -8,9 +8,7 @@ import Foundation -/** - This class can be used to mock `UserDefaults`. - */ +/// This class can be used to mock `UserDefaults`. open class MockUserDefaults: UserDefaults, Mockable { public lazy var boolRef = MockReference(bool)