Sources/AmiiboService/Internal/Protocols/KeyNameFilter.swift

@@ -12,7 +12,7 @@
 // 
 // ===----------------------------------------------------------------------===
 
-/// A protocol that defines filters that might contain `key` and/or `name` values.
+/// A protocol that defines filters containing optional `key` and/or `name` values for querying resources.
 protocol KeyNameFilter {
     
     // MARK: Properties

Sources/AmiiboService/Internal/Protocols/KeyNameModel.swift

@@ -12,15 +12,15 @@
 // 
 // ===----------------------------------------------------------------------===
 
-/// A protocol that defines decodable models containing the `key` and `name` properties.
+/// A protocol that defines models containing a `key` and `name` pair.
 protocol KeyNameModel: Sendable, Hashable {
     
     // MARK: Properties
     
-    /// A key.
+    /// A hexadecimal key that uniquely identifies this model.
     var key: String { get }
     
-    /// A name.
+    /// A display name for this model.
     var name: String { get }
     
     // MARK: Initializers

Sources/AmiiboService/Internal/Transcoders/ISOTimestampTranscoder.swift

@@ -31,10 +31,16 @@ extension ISOTimestampTranscoder: DateTranscoder {
     
     // MARK: Functions
     
+    /// Encodes a date into an ISO timestamp string.
+    /// - Parameter date: A date to encode.
+    /// - Returns: A string representation of the date in `yyyy-MM-dd'T'HH:mm:ss.SSSSSS` format.
     func encode(_ date: Date) throws -> String {
         dateFormatter.string(from: date)
     }
     
+    /// Decodes an ISO timestamp string into a date.
+    /// - Parameter string: A string to decode.
+    /// - Returns: A date parsed from the string, or the Unix epoch if the string cannot be parsed.
     func decode(_ string: String) throws -> Date {
         dateFormatter.date(from: string) ?? .init()
     }

Sources/AmiiboService/Public/Clients/AmiiboLiveClient.swift

@@ -16,18 +16,18 @@ import Foundation
 import OpenAPIRuntime
 import OpenAPIURLSession
 
-/// A type that implements a live client to the online service.
+/// A type that implements a live client to the [Amiibo API](https://www.amiiboapi.org) online service.
 public struct AmiiboLiveClient: Sendable {
     
     // MARK: Properties
     
-    /// A client generated by the `OpenAPIRuntime` library.
+    /// A client generated by the OpenAPI Runtime library to perform API calls.
     private let client: Client
     
     // MARK: Initializers
     
-    /// Initializes this client.
-    /// - Parameter transport: A transport that performs HTTP operations.
+    /// Initializes this client with a transport for performing HTTP operations.
+    /// - Parameter transport: A transport that performs HTTP operations. Defaults to a `URLSessionTransport` using the shared session.
     public init(transport: any ClientTransport = URLSessionTransport()) {
         self.client = .init(
             // The force unwrapping implemented below assumes that the server definition from the OpenAPI specification is correct.
@@ -415,9 +415,9 @@ private extension AmiiboLiveClient {
         }
     }
     
-    /// Maps a given error to a `AmiiboServiceError` error.
+    /// Maps a given error to an ``AmiiboServiceError`` error.
     /// - Parameter error: An error to map.
-    /// - Throws: An ``AmiiboServiceError`` error.
+    /// - Throws: An ``AmiiboServiceError`` error that corresponds to the given error.
     func handle(error: any Error) throws -> Never {
         switch error {
         case is CancellationError:

Sources/AmiiboService/Public/Errors/AmiiboServiceError.swift

@@ -14,19 +14,19 @@
 
 /// A representation of all the possible errors that the ``AmiiboService`` service could throw.
 public enum AmiiboServiceError: Error {
-    /// A bad request has been given to the client.
+    /// The request was malformed or contained invalid filter parameters.
     case badRequest
-    /// A call to an endpoint has been cancelled by the user.
+    /// The request was cancelled before a response was received.
     case cancelled
-    /// A response cannot be decoded.
+    /// The response body could not be decoded into the expected model.
     case decoding
-    /// An online service is not currently available.
+    /// The backend service is currently unreachable due to a network or server issue.
     case notAvailable
-    /// A response cannot be found.
+    /// No results were found matching the given filter criteria.
     case notFound
-    /// An undocumented/unsupported status code error.
+    /// The server returned an undocumented HTTP status code.
     case undocumented(_ statusCode: Int)
-    /// An unknown error.
+    /// An unexpected error that does not fall into any other category.
     case unknown
 }
 

Sources/AmiiboService/Public/Models/Amiibo.swift

@@ -19,34 +19,34 @@ public struct Amiibo: Sendable, Hashable {
     
     // MARK: Properties
     
-    /// A game character.
+    /// The name of the game character associated with this amiibo.
     public let gameCharacter: String
     
-    /// A game series.
+    /// The name of the game series associated with this amiibo.
     public let gameSeries: String
 
-    /// The first 8 hexadecimal characters of an identifier.
+    /// The first 8 hexadecimal characters of the amiibo identifier.
     public let head: String
     
-    /// An image link.
+    /// A URL string pointing to the image of this amiibo.
     public let image: String
 
-    /// An amiibo name.
+    /// The name of this amiibo.
     public let name: String
 
-    /// A game platform type, if any.
+    /// The game platform data for this amiibo, if available.
     public let platform: Platform?
     
-    /// A release date.
+    /// The release dates of this amiibo across different regions.
     public let release: Release
 
-    /// An amiibo series.
+    /// The name of the amiibo series this amiibo belongs to.
     public let series: String
     
-    /// The last 8 hexadecimal characters of an identifier.
+    /// The last 8 hexadecimal characters of the amiibo identifier.
     public let tail: String
     
-    /// An amiibo type.
+    /// The type of this amiibo (e.g., Figure, Card, Yarn, Band).
     public let type: String
     
     // MARK: Initializers
@@ -73,12 +73,12 @@ public struct Amiibo: Sendable, Hashable {
     
     // MARK: Computed
     
-    /// An identifier.
+    /// The full 16-character hexadecimal identifier, composed of the ``head`` and ``tail``.
     public var identifier: String {
         head + tail
     }
     
-    /// A URL related to an image link, if any.
+    /// A URL constructed from the ``image`` string, if valid.
     public var imageURL: URL? {
         .init(string: image)
     }

Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Game.swift

@@ -18,13 +18,13 @@ extension Amiibo {
         
         // MARK: Properties
         
-        /// A list of identifiers.
+        /// A list of game identifiers associated with this game.
         public let identifiers: [String]
         
-        /// A name.
+        /// The name of this game.
         public let name: String
         
-        /// A list of amiibo usages, if any.
+        /// A list of amiibo usages within this game, if available.
         public let usages: [Usage]?
         
         // MARK: Initializers

Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Platform.swift

@@ -13,7 +13,7 @@
 // ===----------------------------------------------------------------------===
 
 extension Amiibo {
-    /// A model that represents a collection of  `Switch`,  `Switch 2`, `3DS`, and `WiiU` games related to an amiibo.
+    /// A model that represents a collection of `Switch`, `Switch 2`, `3DS`, and `Wii U` games related to an amiibo.
     public struct Platform: Sendable, Hashable {
         
         // MARK: Properties
@@ -27,7 +27,7 @@ extension Amiibo {
         /// A list of `3DS` games related to an amiibo.
         public let threeDS: [Game]
         
-        /// A list of `WiiU` games related to an amiibo.
+        /// A list of `Wii U` games related to an amiibo.
         public let wiiU: [Game]
         
         // MARK: Initializers
@@ -40,7 +40,7 @@ extension Amiibo {
         ///   - switch: A list of `Switch` games related to an amiibo, if any.
         ///   - switch2: A list of `Switch 2` games related to an amiibo, if any.
         ///   - threeDS: A list of `3DS` games related to an amiibo, if any.
-        ///   - wiiU: A list of `WiiU` games related to an amiibo, if any.
+        ///   - wiiU: A list of `Wii U` games related to an amiibo, if any.
         init?(
             _ `switch`: [Components.Schemas.AmiiboGame]?,
             _ switch2: [Components.Schemas.AmiiboGame]?,

Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Release.swift

@@ -15,7 +15,7 @@
 import Foundation
 
 extension Amiibo {
-    /// A model that represents a collection of release dates related to an amiibo.
+    /// A model that represents the regional release dates of an amiibo.
     public struct Release: Sendable, Hashable {
         
         // MARK: Properties

Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Usage.swift

@@ -18,10 +18,10 @@ extension Amiibo {
         
         // MARK: Properties
         
-        /// An explanation of how to use an amiibo.
+        /// A description of how the amiibo is used within the game.
         public let explanation: String
         
-        /// A flag that indicates whether an amiibo can save game data in it.
+        /// A flag that indicates whether the amiibo can save game data.
         public let isWriteable: Bool
         
         // MARK: Initializers

Sources/AmiiboService/Public/Models/AmiiboSeries.swift

@@ -17,10 +17,10 @@ public struct AmiiboSeries: KeyNameModel {
 
     // MARK: Properties
 
-    /// An amiibo series key.
+    /// The hexadecimal key that uniquely identifies this amiibo series.
     public let key: String
 
-    /// An amiibo series name.
+    /// The name of this amiibo series.
     public let name: String
     
     // MARK: Initializers

Sources/AmiiboService/Public/Models/AmiiboType.swift

@@ -17,10 +17,10 @@ public struct AmiiboType: KeyNameModel {
 
     // MARK: Properties
 
-    /// An amiibo type key.
+    /// The hexadecimal key that uniquely identifies this amiibo type.
     public let key: String
 
-    /// An amiibo type name.
+    /// The name of this amiibo type (e.g., Figure, Card, Yarn, Band).
     public let name: String
     
     // MARK: Initializers

Sources/AmiiboService/Public/Models/GameCharacter.swift

@@ -17,10 +17,10 @@ public struct GameCharacter: KeyNameModel {
 
     // MARK: Properties
 
-    /// A game character key.
+    /// The hexadecimal key that uniquely identifies this game character.
     public let key: String
 
-    /// A game character  name.
+    /// The name of this game character.
     public let name: String
     
     // MARK: Initializers

Sources/AmiiboService/Public/Models/GameSeries.swift

@@ -17,10 +17,10 @@ public struct GameSeries: KeyNameModel {
 
     // MARK: Properties
 
-    /// A game series key.
+    /// The hexadecimal key that uniquely identifies this game series.
     public let key: String
 
-    /// A game series name.
+    /// The name of this game series.
     public let name: String
     
     // MARK: Initializers

Tests/AmiiboService/Helpers/Clients/AmiiboMockClient.swift

@@ -15,30 +15,30 @@
 import AmiiboService
 import Foundation
 
-/// A type that implements a mock client, for testing purposes.
+/// A mock implementation of ``AmiiboClient`` that returns pre-configured data or throws pre-configured errors, for testing purposes.
 struct AmiiboMockClient {
     
     // MARK: Properties
     
-    /// A list of amiibo items to return, if any.
+    /// The list of amiibo items to return when ``getAmiibos(by:)`` is called, or `nil` to trigger a ``AmiiboServiceError/notFound`` error.
     private let amiibos: [Amiibo]?
     
-    /// A list of amiibo series to return, if any.
+    /// The list of amiibo series to return when ``getAmiiboSeries(by:)`` is called, or `nil` to trigger a ``AmiiboServiceError/notFound`` error.
     private let amiiboSeries: [AmiiboSeries]?
     
-    /// A list of amiibo types to return, if any.
+    /// The list of amiibo types to return when ``getAmiiboTypes(by:)`` is called, or `nil` to trigger a ``AmiiboServiceError/notFound`` error.
     private let amiiboTypes: [AmiiboType]?
     
-    /// An error to throw, if any.
+    /// An error to throw before returning any data. Takes precedence over stored data when set.
     private let error: AmiiboServiceError?
     
-    /// A list of game characters to return, if any.
+    /// The list of game characters to return when ``getGameCharacters(by:)`` is called, or `nil` to trigger a ``AmiiboServiceError/notFound`` error.
     private let gameCharacters: [GameCharacter]?
     
-    /// A list of game series to return, if any.
+    /// The list of game series to return when ``getGameSeries(by:)`` is called, or `nil` to trigger a ``AmiiboServiceError/notFound`` error.
     private let gameSeries: [GameSeries]?
     
-    /// A last updated date to return, if any.
+    /// The last updated date to return when ``getLastUpdated()`` is called, or `nil` to trigger a ``AmiiboServiceError/notFound`` error.
     private let lastUpdated: Date?
     
     // MARK: Initializers
@@ -234,8 +234,8 @@ private extension AmiiboMockClient {
         return lastUpdated
     }
     
-    /// Throws an error if it has been provided,
-    /// - Throws: An ``AmiiboServiceError`` error in case an error has been provided.
+    /// Throws the configured error if one has been provided.
+    /// - Throws: An ``AmiiboServiceError`` error if one was configured during initialization.
     func throwErrorIfExists() throws(AmiiboServiceError) {
         if let error {
             throw error