Improved the public API documentation in the library.

2026-09-14 12:07:53 +02:00
parent aa135cb04a
commit 1de99d643a
10 changed files with 87 additions and 81 deletions
@@ -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.
+    ///   - head: The first 8 hexadecimal characters of an identifier to match, if any. Shorter values match as a prefix.
-    ///   - tail: A last part of an identifier to filter the result, if any.
+    ///   - tail: The last 8 hexadecimal characters of an identifier to match, if any. Shorter values match as a prefix.
-    ///   - identifier: An amiibo identifier to filter the result, if any.
+    ///   - identifier: A full 16-character hexadecimal identifier to match, if any.
-    ///   - name: An amiibo name to filter the result, if any.
+    ///   - name: An amiibo name, or part of one, to match, if any.
-    ///   - type: An amiibo type to filter the result, if any.
+    ///   - type: An amiibo type key or name to match, if any.
-    ///   - series: An amiibo series to filter the result, if any.
+    ///   - series: An amiibo series key or name to match, if any.
-    ///   - gameCharacter: A game character to filter the result, if any.
+    ///   - gameCharacter: A game character key or name to match, if any.
-    ///   - gameSeries: A game series to filter the result, if any.
+    ///   - gameSeries: A game series key or name to match, if any.
-    ///   - showGames: A flag indicating whether to include games in the response, if any.
+    ///   - showGames: A flag that indicates whether to include related games in ``Amiibo/platform``. `nil` means `false`.
-    ///   - showUsage: A flag indicating whether to include amiibo usages in games in the response, if any.
+    ///   - 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.
+    /// Initializes a filter that matches the amiibo series with a given key.
-    /// - Parameter key: A key to return.
+    /// - 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.
+    /// Initializes a filter that matches amiibo series by name.
-    /// - Parameter name: A name to return.
+    /// - 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.
+    /// Initializes a filter that matches the amiibo type with a given key.
-    /// - Parameter key: A key to return.
+    /// - 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.
+    /// Initializes a filter that matches amiibo types by name.
-    /// - Parameter name: A name to return.
+    /// - 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.
+    /// Initializes a filter that matches the game character with a given key.
-    /// - Parameter key: A key to return.
+    /// - 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.
+    /// Initializes a filter that matches game characters by name.
-    /// - Parameter name: A name to return.
+    /// - 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.
+    /// Initializes a filter that matches the game series with a given key.
-    /// - Parameter key: A key to return.
+    /// - 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.
+    /// Initializes a filter that matches game series by name.
-    /// - Parameter name: A name to return.
+    /// - 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.
+    /// Initializes this service with a client.
-    /// - Parameter client: A client to use to interact with the endpoints.
+    /// - Parameter client: The client that performs the calls. Defaults to ``AmiiboLiveClient``.
    public init(client: some AmiiboClient = AmiiboLiveClient()) {
        self.client = client
    }