Improved the public API documentation in the library.
This commit is contained in:
@@ -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)
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user