Sources/Services/AmiiboService.swift

@@ -1,6 +1,9 @@
 import Foundation
 
-public struct AmiiboService {
+/// This service provides the interface to make remote API calls to the [Amiibo API](https://www.amiiboapi.com) and, subsequently, handle its responses.
+///
+/// Given that this remote service is a read-only API, this service will exclusively return decoded models or entities in cases the requests are successful, or it will throw errors otherwise.
+public actor AmiiboService {
     
     // MARK: Properties
     
@@ -8,7 +11,9 @@ public struct AmiiboService {
     
     // MARK: Initialisers
     
-    init(configuration: URLSessionConfiguration) {
+    /// Initialises this service.
+    /// - Parameter configuration: The `URLSessionConfiguration` configuration to use to set this service.
+    public init(configuration: URLSessionConfiguration) {
         self.client = .init(configuration: configuration)
     }
     
@@ -20,6 +25,10 @@ extension AmiiboService: Service {
     
     // MARK: Functions
     
+    /// Retrieves a list of amiibos from a remote location that matches a given filter criteria.
+    /// - Parameter filter: A ``AmiiboFilter`` instance that contains the filtering criteria.
+    /// - Returns: A list of decoded ``Amiibo`` instances that matches the given filter criteria.
+    /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed.
     public func amiibos(
         filter: AmiiboFilter = .init()
     ) async throws -> [Amiibo] {
@@ -31,6 +40,10 @@ extension AmiiboService: Service {
         ).items
     }
     
+    /// Retrieves a list of amiibo series from a remote location that matches a given filter criteria.
+    /// - Parameter filter: A ``AmiiboSeriesFilter`` instance that contains the filtering criteria.
+    /// - Returns: A list of decoded ``AmiiboSeries`` instances that matches the given filter criteria.
+    /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed.
     public func amiiboSeries(
         filter: AmiiboSeriesFilter = .init()
     ) async throws -> [AmiiboSeries] {
@@ -42,6 +55,10 @@ extension AmiiboService: Service {
         ).items
     }
     
+    /// Retrieves a list of amiibo types from a remote location that matches a given filter criteria.
+    /// - Parameter filter: A ``AmiiboTypeFilter`` instance that contains the filtering criteria.
+    /// - Returns: A list of decoded ``AmiiboType`` instances that matches the given filter criteria.
+    /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed.
     public func amiiboTypes(
         filter: AmiiboTypeFilter = .init()
     ) async throws -> [AmiiboType] {
@@ -53,6 +70,10 @@ extension AmiiboService: Service {
         ).items
     }
     
+    /// Retrieves a list of characters from a remote location that matches a given filter criteria.
+    /// - Parameter filter: A ``CharacterFilter`` instance that contains the filtering criteria.
+    /// - Returns: A list of decoded ``Character`` instances that matches the given filter criteria.
+    /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed.
     public func characters(
         filter: CharacterFilter = .init()
     ) async throws -> [Character] {
@@ -64,6 +85,10 @@ extension AmiiboService: Service {
         ).items
     }
     
+    /// Retrieves a list of game series from a remote location that matches a given filter criteria.
+    /// - Parameter filter: A ``GameSeriesFilter`` instance that contains the filtering criteria.
+    /// - Returns: A list of decoded ``GameSeries`` instances that matches the given filter criteria.
+    /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed.
     public func gameSeries(
         filter: GameSeriesFilter = .init()
     ) async throws -> [GameSeries] {
@@ -75,6 +100,9 @@ extension AmiiboService: Service {
         ).items
     }
 
+    /// Retrieves the date in which the remote API was last updated.
+    /// - Returns: A `Date` instance that represents the date in which the remote API was last updated.
+    /// - Throws: A ``AmiiboClientError`` is thrown in case a request failed, or a `DecodingError` is thrown in case the decoding of some object failed.
     public func lastUpdated() async throws -> Date {
         client.setDateDecodingStrategy(.formatted(.dateAndTime))