Update docs

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<Arguments, Result>: Identifiable {
 
     public init(_ function: @escaping (Arguments) async throws -> Result) {

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() {}

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<Arguments, Result>: 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 {}

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<Arguments, Result>: Identifiable {
 
     public init(_ function: @escaping (Arguments) throws -> Result) {

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<Arguments, Result>(
         _ ref: MockReference<Arguments, Result>,
         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<Arguments, Result>(
         _ ref: AsyncMockReference<Arguments, Result>,
         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<Arguments, Result>(
         _ ref: MockReference<Arguments, Result>,
         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<Arguments, Result>(
         _ ref: AsyncMockReference<Arguments, Result>,
         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<Arguments, Result>(
         _ ref: MockReference<Arguments, Result?>,
         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<Arguments, Result>(
         _ ref: AsyncMockReference<Arguments, Result?>,
         args: Arguments