Improved the overall documentation for the public and internal types in the package.

2026-03-23 00:25:38 +01:00
parent 69d7681139
commit cd01c27544
15 changed files with 62 additions and 56 deletions
@@ -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
@@ -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
@@ -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()
    }
@@ -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.
+    /// Initializes this client with a transport for performing HTTP operations.
-    /// - Parameter transport: A transport that performs 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:
@@ -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
 }
@@ -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)
    }
@@ -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
@@ -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]?,
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 the configured error if one has been provided.
-    /// - Throws: An ``AmiiboServiceError`` error in case an error has been provided.
+    /// - Throws: An ``AmiiboServiceError`` error if one was configured during initialization.
    func throwErrorIfExists() throws(AmiiboServiceError) {
        if let error {
            throw error