From cd01c2754453bd90c534c31815f46bbef01907ff Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Mon, 23 Mar 2026 00:25:38 +0100 Subject: [PATCH] Improved the overall documentation for the public and internal types in the package. --- .../Internal/Protocols/KeyNameFilter.swift | 2 +- .../Internal/Protocols/KeyNameModel.swift | 6 ++--- .../Transcoders/ISOTimestampTranscoder.swift | 6 +++++ .../Public/Clients/AmiiboLiveClient.swift | 12 +++++----- .../Public/Errors/AmiiboServiceError.swift | 14 +++++------ .../AmiiboService/Public/Models/Amiibo.swift | 24 +++++++++---------- .../Public/Models/Amiibo/Amiibo+Game.swift | 6 ++--- .../Models/Amiibo/Amiibo+Platform.swift | 6 ++--- .../Public/Models/Amiibo/Amiibo+Release.swift | 2 +- .../Public/Models/Amiibo/Amiibo+Usage.swift | 4 ++-- .../Public/Models/AmiiboSeries.swift | 4 ++-- .../Public/Models/AmiiboType.swift | 4 ++-- .../Public/Models/GameCharacter.swift | 4 ++-- .../Public/Models/GameSeries.swift | 4 ++-- .../Helpers/Clients/AmiiboMockClient.swift | 20 ++++++++-------- 15 files changed, 62 insertions(+), 56 deletions(-) diff --git a/Sources/AmiiboService/Internal/Protocols/KeyNameFilter.swift b/Sources/AmiiboService/Internal/Protocols/KeyNameFilter.swift index 804f9cf..908ad6c 100644 --- a/Sources/AmiiboService/Internal/Protocols/KeyNameFilter.swift +++ b/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 diff --git a/Sources/AmiiboService/Internal/Protocols/KeyNameModel.swift b/Sources/AmiiboService/Internal/Protocols/KeyNameModel.swift index 9c591c3..8e03692 100644 --- a/Sources/AmiiboService/Internal/Protocols/KeyNameModel.swift +++ b/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 diff --git a/Sources/AmiiboService/Internal/Transcoders/ISOTimestampTranscoder.swift b/Sources/AmiiboService/Internal/Transcoders/ISOTimestampTranscoder.swift index 1d4028c..d1d1011 100644 --- a/Sources/AmiiboService/Internal/Transcoders/ISOTimestampTranscoder.swift +++ b/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() } diff --git a/Sources/AmiiboService/Public/Clients/AmiiboLiveClient.swift b/Sources/AmiiboService/Public/Clients/AmiiboLiveClient.swift index 265aeea..08be7f7 100644 --- a/Sources/AmiiboService/Public/Clients/AmiiboLiveClient.swift +++ b/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: diff --git a/Sources/AmiiboService/Public/Errors/AmiiboServiceError.swift b/Sources/AmiiboService/Public/Errors/AmiiboServiceError.swift index ece8579..2864365 100644 --- a/Sources/AmiiboService/Public/Errors/AmiiboServiceError.swift +++ b/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 } diff --git a/Sources/AmiiboService/Public/Models/Amiibo.swift b/Sources/AmiiboService/Public/Models/Amiibo.swift index 22db978..bd03f04 100644 --- a/Sources/AmiiboService/Public/Models/Amiibo.swift +++ b/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) } diff --git a/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Game.swift b/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Game.swift index 0eeea89..0f8502a 100644 --- a/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Game.swift +++ b/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 diff --git a/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Platform.swift b/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Platform.swift index 9b56a13..dadc764 100644 --- a/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Platform.swift +++ b/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]?, diff --git a/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Release.swift b/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Release.swift index b8e4ffd..e2211c4 100644 --- a/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Release.swift +++ b/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 diff --git a/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Usage.swift b/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Usage.swift index 62d8663..a04fbda 100644 --- a/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Usage.swift +++ b/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 diff --git a/Sources/AmiiboService/Public/Models/AmiiboSeries.swift b/Sources/AmiiboService/Public/Models/AmiiboSeries.swift index 2fd7a17..2e4d0a5 100644 --- a/Sources/AmiiboService/Public/Models/AmiiboSeries.swift +++ b/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 diff --git a/Sources/AmiiboService/Public/Models/AmiiboType.swift b/Sources/AmiiboService/Public/Models/AmiiboType.swift index 681ebb8..2ea8bfe 100644 --- a/Sources/AmiiboService/Public/Models/AmiiboType.swift +++ b/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 diff --git a/Sources/AmiiboService/Public/Models/GameCharacter.swift b/Sources/AmiiboService/Public/Models/GameCharacter.swift index e43e391..c323c60 100644 --- a/Sources/AmiiboService/Public/Models/GameCharacter.swift +++ b/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 diff --git a/Sources/AmiiboService/Public/Models/GameSeries.swift b/Sources/AmiiboService/Public/Models/GameSeries.swift index 5e1e0da..6667f7d 100644 --- a/Sources/AmiiboService/Public/Models/GameSeries.swift +++ b/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 diff --git a/Tests/AmiiboService/Helpers/Clients/AmiiboMockClient.swift b/Tests/AmiiboService/Helpers/Clients/AmiiboMockClient.swift index 67eb267..f8563a4 100644 --- a/Tests/AmiiboService/Helpers/Clients/AmiiboMockClient.swift +++ b/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