From 7d80ba3470a320efc6a5f3cd9e504ce593a6ec6a Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Sun, 23 Jul 2023 15:03:16 +0200 Subject: [PATCH] Updated some texts for the AmiiboService documentation. --- Sources/AmiiboService.docc/AmiiboService.md | 31 ++++++++++++-------- Sources/AmiiboService.docc/GettingStarted.md | 2 +- Sources/Models/DTO/LastUpdated.swift | 4 +-- Sources/Services/AmiiboService.swift | 12 ++++---- 4 files changed, 27 insertions(+), 22 deletions(-) diff --git a/Sources/AmiiboService.docc/AmiiboService.md b/Sources/AmiiboService.docc/AmiiboService.md index 65d18ca..6308e14 100644 --- a/Sources/AmiiboService.docc/AmiiboService.md +++ b/Sources/AmiiboService.docc/AmiiboService.md @@ -4,7 +4,11 @@ Ready-to-use service that retrieves decoded entities from any of the [Amiibo API ## Overview -**AmiiboService** provides a service, filters and models for retrieving data from the remote [Amiibo API](https://www.amiiboapi.com) endpoints to use in libraries and applications targeting not only Apple platforms, such as *iOS*, *macOS*, *tvOS*, and *watchOS*, but also *Linux*. This package provides structures that can be used to include filters to the requests to send to the remote service if required. In addition, the structures to model the kinds of data coming in from those responses into entities are also provided. +**AmiiboService** provides a service for retrieving data from the remote [Amiibo API](https://www.amiiboapi.com) endpoints that could be used in either in libraries and applications, targeting not only Apple platforms, such as *iOS*, *macOS*, *tvOS*, *watchOS*, and *xrOS*; but *Linux* and *Windows* platforms as well. + +This package provides all the necessary components to the developers to: +* data filtering parameters to the requests to send to the remote service, if required; +* decoded models from the data coming in from those responses. ## Topics @@ -13,7 +17,18 @@ Ready-to-use service that retrieves decoded entities from any of the [Amiibo API - - ``AmiiboService/AmiiboService`` -### Filter data when making requests +### Models + +- ``DTO`` +- ``DTO/Amiibo`` +- ``DTO/KeyName`` +- ``DTO/AmiiboSeries`` +- ``DTO/AmiiboType`` +- ``DTO/Character`` +- ``DTO/GameSeries`` +- ``DTO/LastUpdated`` + +### Filters - ``AmiiboFilter`` - ``KeyNameFilter`` @@ -22,16 +37,6 @@ Ready-to-use service that retrieves decoded entities from any of the [Amiibo API - ``CharacterFilter`` - ``GameSeriesFilter`` -### Models to decode the data coming from the responses - -- ``Amiibo`` -- ``KeyName`` -- ``AmiiboSeries`` -- ``AmiiboType`` -- ``Character`` -- ``GameSeries`` -- ``LastUpdated`` - -### Errors that can be thrown by the service +### Errors - ``AmiiboClientError`` diff --git a/Sources/AmiiboService.docc/GettingStarted.md b/Sources/AmiiboService.docc/GettingStarted.md index cafcbf4..c536888 100644 --- a/Sources/AmiiboService.docc/GettingStarted.md +++ b/Sources/AmiiboService.docc/GettingStarted.md @@ -80,5 +80,5 @@ This service provides these following functions, which all basically are meant t It is certainly important to highlight two points here: -1. these functions support the `async/await` feature of the Swift programming language, thus they should be called within a context that already uses this feature; +1. these functions support the `Swift concurrency` (or `async/await`) feature of the Swift programming language, thus they should be called within a context that already uses this feature; 2. these functions would throw an error in case any issue occurred while they are executing, so it is recommendable to handle the error appropriately to guarantee the proper continuation of the application and also, a proper user experience. diff --git a/Sources/Models/DTO/LastUpdated.swift b/Sources/Models/DTO/LastUpdated.swift index ed4f197..94224d0 100644 --- a/Sources/Models/DTO/LastUpdated.swift +++ b/Sources/Models/DTO/LastUpdated.swift @@ -12,10 +12,10 @@ import Foundation -extension DTO { +public extension DTO { /// This model represents the latest date when the remote API has been updated. - public struct LastUpdated { + struct LastUpdated { // MARK: Properties diff --git a/Sources/Services/AmiiboService.swift b/Sources/Services/AmiiboService.swift index ef4ee3c..feb6e11 100644 --- a/Sources/Services/AmiiboService.swift +++ b/Sources/Services/AmiiboService.swift @@ -43,7 +43,7 @@ extension AmiiboService: Service { /// 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. + /// - Returns: A list of decoded ``DTO.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() @@ -58,7 +58,7 @@ extension AmiiboService: Service { /// 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. + /// - Returns: A list of decoded ``DTO.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() @@ -73,7 +73,7 @@ extension AmiiboService: Service { /// 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. + /// - Returns: A list of decoded ``DTO.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() @@ -88,7 +88,7 @@ extension AmiiboService: Service { /// 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. + /// - Returns: A list of decoded ``DTO.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() @@ -103,7 +103,7 @@ extension AmiiboService: Service { /// 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. + /// - Returns: A list of decoded ``DTO.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() @@ -117,7 +117,7 @@ extension AmiiboService: Service { } /// 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. + /// - Returns: A decoded `DTO.LastUpdated` 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 -> DTO.LastUpdated { client.setDateDecodingStrategy(.formatted(.dateAndTime))