From 1de99d643a42fe2b2b94bce7da83425b4fb73ec7 Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Mon, 14 Sep 2026 12:07:53 +0200 Subject: [PATCH] Improved the public API documentation in the library. --- .../Public/Errors/AmiiboServiceError.swift | 4 +- .../Public/Filters/AmiiboFilter.swift | 56 ++++++++++--------- .../Public/Filters/AmiiboSeriesFilter.swift | 20 +++---- .../Public/Filters/AmiiboTypeFilter.swift | 18 +++--- .../Public/Filters/GameCharacterFilter.swift | 22 ++++---- .../Public/Filters/GameSeriesFilter.swift | 22 ++++---- .../AmiiboService/Public/Models/Amiibo.swift | 4 +- .../Public/Models/Amiibo/Amiibo+Game.swift | 2 +- .../Public/Protocols/AmiiboClient.swift | 4 +- .../Public/Services/AmiiboService.swift | 16 +++--- 10 files changed, 87 insertions(+), 81 deletions(-) diff --git a/Sources/AmiiboService/Public/Errors/AmiiboServiceError.swift b/Sources/AmiiboService/Public/Errors/AmiiboServiceError.swift index e2817d9..9535187 100644 --- a/Sources/AmiiboService/Public/Errors/AmiiboServiceError.swift +++ b/Sources/AmiiboService/Public/Errors/AmiiboServiceError.swift @@ -14,7 +14,7 @@ import Foundation -/// A representation of all the possible errors that the ``AmiiboService`` service could throw. +/// An error thrown by ``AmiiboService`` and ``AmiiboClient`` methods. public enum AmiiboServiceError: Error { /// The request was malformed or contained invalid filter parameters. case badRequest @@ -25,6 +25,8 @@ public enum AmiiboServiceError: Error { /// The backend service is currently unreachable due to a network or server issue. case notAvailable /// No results were found matching the given filter criteria. + /// + /// When no amiibos match, ``AmiiboService/getAmiibos(_:)`` returns an empty array instead of throwing this error. case notFound /// The server returned an undocumented HTTP status code. case undocumented(_ statusCode: Int) diff --git a/Sources/AmiiboService/Public/Filters/AmiiboFilter.swift b/Sources/AmiiboService/Public/Filters/AmiiboFilter.swift index c89c0d0..40c987d 100644 --- a/Sources/AmiiboService/Public/Filters/AmiiboFilter.swift +++ b/Sources/AmiiboService/Public/Filters/AmiiboFilter.swift @@ -12,55 +12,57 @@ // // ===----------------------------------------------------------------------=== -/// A type that contains values to fine-tune a response when requesting amiibo items. +/// A filter for amiibo requests. +/// +/// Values left as `nil` do not restrict the result. public struct AmiiboFilter: Sendable { - + // MARK: Properties - - /// A game character to filter the result, if any. + + /// A game character key or name to match, if any. public let gameCharacter: String? - /// A game series to filter the result, if any. + /// A game series key or name to match, if any. public let gameSeries: String? - - /// A first part of an identifier to filter the result, if any. + + /// The first 8 hexadecimal characters of an identifier to match, if any. Shorter values match as a prefix. public let head: String? - /// An amiibo identifier to filter the result, if any. + /// A full 16-character hexadecimal identifier to match, if any. public let identifier: String? - /// An amiibo name to filter the result, if any. + /// An amiibo name, or part of one, to match, if any. public let name: String? - /// An amiibo series to filter the result, if any. + /// An amiibo series key or name to match, if any. public let series: String? - /// A flag indicating whether to include games in the response, if any. + /// A flag that indicates whether to include related games in ``Amiibo/platform``. `nil` means `false`. public let showGames: Bool? - /// A flag indicating whether to include amiibo usages in games in the response, if any. + /// A flag that indicates whether to include related games and their amiibo usages in ``Amiibo/platform``. `nil` means `false`. public let showUsage: Bool? - - /// A last part of an identifier to filter the result, if any. + + /// The last 8 hexadecimal characters of an identifier to match, if any. Shorter values match as a prefix. public let tail: String? - /// An amiibo type to filter the result, if any. + /// An amiibo type key or name to match, if any. public let type: String? - + // MARK: Initializers - + /// Initializes this filter. /// - Parameters: - /// - head: A first part of an identifier to filter the result, if any. - /// - tail: A last part of an identifier to filter the result, if any. - /// - identifier: An amiibo identifier to filter the result, if any. - /// - name: An amiibo name to filter the result, if any. - /// - type: An amiibo type to filter the result, if any. - /// - series: An amiibo series to filter the result, if any. - /// - gameCharacter: A game character to filter the result, if any. - /// - gameSeries: A game series to filter the result, if any. - /// - showGames: A flag indicating whether to include games in the response, if any. - /// - showUsage: A flag indicating whether to include amiibo usages in games in the response, if any. + /// - head: The first 8 hexadecimal characters of an identifier to match, if any. Shorter values match as a prefix. + /// - tail: The last 8 hexadecimal characters of an identifier to match, if any. Shorter values match as a prefix. + /// - identifier: A full 16-character hexadecimal identifier to match, if any. + /// - name: An amiibo name, or part of one, to match, if any. + /// - type: An amiibo type key or name to match, if any. + /// - series: An amiibo series key or name to match, if any. + /// - gameCharacter: A game character key or name to match, if any. + /// - gameSeries: A game series key or name to match, if any. + /// - showGames: A flag that indicates whether to include related games in ``Amiibo/platform``. `nil` means `false`. + /// - showUsage: A flag that indicates whether to include related games and their amiibo usages in ``Amiibo/platform``. `nil` means `false`. public init( head: String? = nil, tail: String? = nil, diff --git a/Sources/AmiiboService/Public/Filters/AmiiboSeriesFilter.swift b/Sources/AmiiboService/Public/Filters/AmiiboSeriesFilter.swift index e018423..cf9fcc7 100644 --- a/Sources/AmiiboService/Public/Filters/AmiiboSeriesFilter.swift +++ b/Sources/AmiiboService/Public/Filters/AmiiboSeriesFilter.swift @@ -12,36 +12,36 @@ // // ===----------------------------------------------------------------------=== -/// A type that contains values to fine-tune a response when requesting amiibo series. +/// A filter for amiibo series requests. public struct AmiiboSeriesFilter: KeyNameFilter, Sendable { - + // TODO: Remove the documentation from the properties and initializers of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?). // MARK: Properties - /// A key to return, if any. + /// A hexadecimal key in `0x` format, such as `0x01`, to match exactly, if any. public let key: String? - /// A name to return, if any. + /// A name, or part of one, to match, if any. public let name: String? - + // MARK: Initializers - /// Initializes this filter without key or name values. + /// Initializes a filter that matches every amiibo series. public init() { self.key = nil self.name = nil } - /// Initializes this filter with a key value. - /// - Parameter key: A key to return. + /// Initializes a filter that matches the amiibo series with a given key. + /// - Parameter key: A hexadecimal key in `0x` format, such as `0x01`. public init(key: String) { self.key = key self.name = nil } - /// Initializes this filter with a name value. - /// - Parameter name: A name to return. + /// Initializes a filter that matches amiibo series by name. + /// - Parameter name: A name, or part of one. public init(name: String) { self.key = nil self.name = name diff --git a/Sources/AmiiboService/Public/Filters/AmiiboTypeFilter.swift b/Sources/AmiiboService/Public/Filters/AmiiboTypeFilter.swift index 5e5769b..8e3d048 100644 --- a/Sources/AmiiboService/Public/Filters/AmiiboTypeFilter.swift +++ b/Sources/AmiiboService/Public/Filters/AmiiboTypeFilter.swift @@ -12,36 +12,36 @@ // // ===----------------------------------------------------------------------=== -/// A type that contains values to fine-tune a response when requesting amiibo types. +/// A filter for amiibo type requests. public struct AmiiboTypeFilter: KeyNameFilter, Sendable { // TODO: Remove the documentation from the properties and initializers of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?). // MARK: Properties - /// A key to return, if any. + /// A hexadecimal key in `0x` format, such as `0x01`, to match exactly, if any. public let key: String? - /// A name to return, if any. + /// A name, or part of one, to match, if any. public let name: String? - + // MARK: Initializers - /// Initializes this filter without key or name values. + /// Initializes a filter that matches every amiibo type. public init() { self.key = nil self.name = nil } - /// Initializes this filter with a key value. - /// - Parameter key: A key to return. + /// Initializes a filter that matches the amiibo type with a given key. + /// - Parameter key: A hexadecimal key in `0x` format, such as `0x01`. public init(key: String) { self.key = key self.name = nil } - /// Initializes this filter with a name value. - /// - Parameter name: A name to return. + /// Initializes a filter that matches amiibo types by name. + /// - Parameter name: A name, or part of one. public init(name: String) { self.key = nil self.name = name diff --git a/Sources/AmiiboService/Public/Filters/GameCharacterFilter.swift b/Sources/AmiiboService/Public/Filters/GameCharacterFilter.swift index 0d8353e..cf5b7ae 100644 --- a/Sources/AmiiboService/Public/Filters/GameCharacterFilter.swift +++ b/Sources/AmiiboService/Public/Filters/GameCharacterFilter.swift @@ -12,36 +12,36 @@ // // ===----------------------------------------------------------------------=== -/// A type that contains values to fine-tune a response when requesting game characters. +/// A filter for game character requests. public struct GameCharacterFilter: KeyNameFilter, Sendable { - + // TODO: Remove the documentation from the properties and initializers of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?). - + // MARK: Properties - /// A key to return, if any. + /// A hexadecimal key in `0x` format, such as `0x0001`, to match exactly, if any. public let key: String? - /// A name to return, if any. + /// A name, or part of one, to match, if any. public let name: String? - + // MARK: Initializers - /// Initializes this filter without key or name values. + /// Initializes a filter that matches every game character. public init() { self.key = nil self.name = nil } - /// Initializes this filter with a key value. - /// - Parameter key: A key to return. + /// Initializes a filter that matches the game character with a given key. + /// - Parameter key: A hexadecimal key in `0x` format, such as `0x0001`. public init(key: String) { self.key = key self.name = nil } - /// Initializes this filter with a name value. - /// - Parameter name: A name to return. + /// Initializes a filter that matches game characters by name. + /// - Parameter name: A name, or part of one. public init(name: String) { self.key = nil self.name = name diff --git a/Sources/AmiiboService/Public/Filters/GameSeriesFilter.swift b/Sources/AmiiboService/Public/Filters/GameSeriesFilter.swift index 386baac..5826c03 100644 --- a/Sources/AmiiboService/Public/Filters/GameSeriesFilter.swift +++ b/Sources/AmiiboService/Public/Filters/GameSeriesFilter.swift @@ -12,36 +12,36 @@ // // ===----------------------------------------------------------------------=== -/// A type that contains values to fine-tune a response when requesting game series. +/// A filter for game series requests. public struct GameSeriesFilter: KeyNameFilter, Sendable { - + // TODO: Remove the documentation from the properties and initializers of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?). - + // MARK: Properties - /// A key to return, if any. + /// A hexadecimal key in `0x` format, such as `0x001`, to match exactly, if any. public let key: String? - /// A name to return, if any. + /// A name, or part of one, to match, if any. public let name: String? - + // MARK: Initializers - /// Initializes this filter without key or name values. + /// Initializes a filter that matches every game series. public init() { self.key = nil self.name = nil } - /// Initializes this filter with a key value. - /// - Parameter key: A key to return. + /// Initializes a filter that matches the game series with a given key. + /// - Parameter key: A hexadecimal key in `0x` format, such as `0x001`. public init(key: String) { self.key = key self.name = nil } - /// Initializes this filter with a name value. - /// - Parameter name: A name to return. + /// Initializes a filter that matches game series by name. + /// - Parameter name: A name, or part of one. public init(name: String) { self.key = nil self.name = name diff --git a/Sources/AmiiboService/Public/Models/Amiibo.swift b/Sources/AmiiboService/Public/Models/Amiibo.swift index bd03f04..239bc8e 100644 --- a/Sources/AmiiboService/Public/Models/Amiibo.swift +++ b/Sources/AmiiboService/Public/Models/Amiibo.swift @@ -34,7 +34,9 @@ public struct Amiibo: Sendable, Hashable { /// The name of this amiibo. public let name: String - /// The game platform data for this amiibo, if available. + /// The related games of this amiibo, grouped by platform. + /// + /// This value is `nil` unless the request sets ``AmiiboFilter/showGames`` or ``AmiiboFilter/showUsage``, or when the amiibo has no related games. public let platform: Platform? /// The release dates of this amiibo across different regions. diff --git a/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Game.swift b/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Game.swift index 0f8502a..2fa719a 100644 --- a/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Game.swift +++ b/Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Game.swift @@ -24,7 +24,7 @@ extension Amiibo { /// The name of this game. public let name: String - /// A list of amiibo usages within this game, if available. + /// A list of amiibo usages within this game, or `nil` unless the request sets ``AmiiboFilter/showUsage``. public let usages: [Usage]? // MARK: Initializers diff --git a/Sources/AmiiboService/Public/Protocols/AmiiboClient.swift b/Sources/AmiiboService/Public/Protocols/AmiiboClient.swift index fc1b3a8..7a695aa 100644 --- a/Sources/AmiiboService/Public/Protocols/AmiiboClient.swift +++ b/Sources/AmiiboService/Public/Protocols/AmiiboClient.swift @@ -14,9 +14,9 @@ import Foundation -/// A protocol that defines API clients containing all available endpoints to interact with. +/// A protocol that defines a client that fetches data from the Amiibo API. /// -/// Conforming types must be `Sendable`, as clients are expected to be used safely across concurrency domains. +/// ``AmiiboLiveClient`` is the default implementation. Conform to this protocol to provide another one, such as a mock for tests. Conforming types must be `Sendable`. public protocol AmiiboClient: Sendable { // MARK: Functions diff --git a/Sources/AmiiboService/Public/Services/AmiiboService.swift b/Sources/AmiiboService/Public/Services/AmiiboService.swift index 1f95cc8..e5e843d 100644 --- a/Sources/AmiiboService/Public/Services/AmiiboService.swift +++ b/Sources/AmiiboService/Public/Services/AmiiboService.swift @@ -14,20 +14,20 @@ import Foundation -/// A type that implements the service that uses a client to make calls. +/// The entry point for fetching data from the Amiibo API. /// -/// This service forwards every call to the ``AmiiboClient`` client injected during initialization, which defaults to an ``AmiiboLiveClient`` instance. This type is `Sendable`, so an instance can be safely shared across concurrency domains. +/// This service forwards every call to the ``AmiiboClient`` passed at initialization, which defaults to ``AmiiboLiveClient``. It is `Sendable`, so you can share an instance across concurrency domains. public struct AmiiboService: Sendable { - + // MARK: Properties - + /// A client to interact with the endpoints. private let client: any AmiiboClient - + // MARK: Initializers - - /// Initializes this service with a specific client type. - /// - Parameter client: A client to use to interact with the endpoints. + + /// Initializes this service with a client. + /// - Parameter client: The client that performs the calls. Defaults to ``AmiiboLiveClient``. public init(client: some AmiiboClient = AmiiboLiveClient()) { self.client = client }