Patched (temporarily) the DocC documentation (#8)

This PR contains the work done to:
* Documented the public properties, initializers, and/or functions of those types conforming to the `APIClient`, `KeyNameFilter`, and `KeyNameModel` protocols, to fix the issue that the protocol documentations cannot be inherited;
* Moved the `AmiiboService` DocC documentation catalog inside the library target;
* Amended the folder structure of the library and test targets;
* Fixed further documentation issues encountered while revising the written documentation;
* Added the `lib-test` task in the `Makefile` file;
* Improved the naming for the existing tasks in the `Makefile` file.

Reviewed-on: #8
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

Sources/AmiiboService/Catalogs/AmiiboService.docc/Library.md

@@ -0,0 +1,82 @@
+# ``AmiiboService``
+
+A library that provides everything the developer needs to interacts with the **Amiibo API** backend service.
+
+## Overview
+
+The `AmiiboService` library is a Swift Package Manager package dependency aims at allowing the developer to interact with the [Amiibo API](https://www.amiiboapi.com) backend service seamlessly, by not only providing the *service* type but also any possible *clients*, *models*, *filters* and *errors* types that might be needed during implementation.
+
+## Design
+
+Although it could have been possible to generate a one-to-one RESTful client based on the Open API specification document that describe the available endpoints of the backend service, it was decided to design a `AmiiboService` service type that removes the complexities of the API design imposed by the backend service, and provides the developer with a simple interface, and a seamless experience.
+
+## Installation
+
+To use the `AmiiboService` library with your package, then add it as a dependency in the `Package.swift` file:
+
+```swift
+let package = Package(
+    // name, platforms, products, etc.
+    dependencies: [
+        .package(url: "https://github.com/rock-n-code/amiibo-service", from: "1.0.0"),
+        // other dependencies
+    ],
+    targets: [
+        .target(
+            name: "SomeTarget", 
+            dependencies: [
+                .product(name: "AmiiboService", package: "amiibo-service"),
+            ]
+        )
+        // other targets
+    ]
+)
+```
+
+It is also possible to use the `AmiiboService` library with your app in Xcode, then add it as a dependency in your Xcode project.
+
+> important: Swift 5.9 or higher is required in order to compile this library.
+
+## Tasks
+
+This library offers a set of ready-to-use project management tasks that the developer could use from the command line. To show the list of tasks on the `Terminal` app, plus display some explanations about each and every one of them; please enter the following command:
+
+```bash
+$ make
+```
+
+## Topics
+
+### Service
+
+- ``AmiiboService``
+
+### Clients
+
+- ``AmiiboClient``
+- ``AmiiboLiveClient``
+- ``AmiiboMockClient``
+
+### Models
+
+- ``Amiibo``
+- ``Amiibo/Game``
+- ``Amiibo/Platform``
+- ``Amiibo/Release``
+- ``Amiibo/Usage``
+- ``AmiiboSeries``
+- ``AmiiboType``
+- ``GameCharacter``
+- ``GameSeries``
+
+### Filters
+
+- ``AmiiboFilter``
+- ``AmiiboSeriesFilter``
+- ``AmiiboTypeFilter``
+- ``GameCharacterFilter``
+- ``GameSeriesFilter``
+
+### Errors
+
+- ``AmiiboServiceError``

Sources/AmiiboService/Internal/Protocols/KeyNameFilter.swift

@@ -15,10 +15,10 @@ protocol KeyNameFilter {
     
     // MARK: Properties
     
-    /// A key to use for filtering, if any.
+    /// A key to return, if any.
     var key: String? { get }
     
-    /// A name to use for filtering, if any.
+    /// A name to return, if any.
     var name: String? { get }
     
     // MARK: Initializers
@@ -27,11 +27,11 @@ protocol KeyNameFilter {
     init()
 
     /// Initializes this filter with a key value.
-    /// - Parameter key: A key to use for filtering.
+    /// - Parameter key: A key to return.
     init(key: String)
     
     /// Initializes this filter with a name value.
-    /// - Parameter name: A name to use for filtering.
+    /// - Parameter name: A name to return.
     init(name: String)
     
 }

Sources/AmiiboService/Public/Clients/AmiiboLiveClient.swift

@@ -37,11 +37,16 @@ public struct AmiiboLiveClient {
 }
 
 // MARK: - APIClient
+// TODO: Remove the documentation from the functions inside the following extension as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
 
 extension AmiiboLiveClient: APIClient {
 
     // MARK: Functions
     
+    /// Gets a list of amiibo items based on a given filter.
+    /// - Parameter filter: A filter to remove unwanted items from the result.
+    /// - Returns: A list of filtered amiibo items.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getAmiibos(
         by filter: AmiiboFilter
     ) async throws(AmiiboServiceError) -> [Amiibo] {
@@ -84,7 +89,11 @@ extension AmiiboLiveClient: APIClient {
             throw AmiiboServiceError.undocumented(statusCode)
         }
     }
-    
+
+    /// Gets a list of amiibo series based on a given filter.
+    /// - Parameter filter: A filter to remove unwanted items from the result.
+    /// - Returns: A list of filtered amiibo series.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getAmiiboSeries(
         by filter: AmiiboSeriesFilter
     ) async throws(AmiiboServiceError) -> [AmiiboSeries] {
@@ -121,7 +130,11 @@ extension AmiiboLiveClient: APIClient {
             throw AmiiboServiceError.undocumented(statusCode)
         }
     }
-    
+ 
+    /// Gets a list of amiibo types based on a given filter.
+    /// - Parameter filter: A filter to remove unwanted items from the result.
+    /// - Returns: A list of filtered amiibo types.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getAmiiboTypes(
         by filter: AmiiboTypeFilter
     ) async throws(AmiiboServiceError) -> [AmiiboType] {
@@ -158,7 +171,11 @@ extension AmiiboLiveClient: APIClient {
             throw AmiiboServiceError.undocumented(statusCode)
         }
     }
-    
+
+    /// Gets a list of game characters based on a given filter.
+    /// - Parameter filter: A filter to remove unwanted items from the result.
+    /// - Returns: A list of filtered game characters.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getGameCharacters(
         by filter: GameCharacterFilter
     ) async throws(AmiiboServiceError) -> [GameCharacter] {
@@ -195,7 +212,11 @@ extension AmiiboLiveClient: APIClient {
             throw AmiiboServiceError.undocumented(statusCode)
         }
     }
-    
+
+    /// Gets a list of game series based on a given filter.
+    /// - Parameter filter: A filter to remove unwanted items from the result.
+    /// - Returns: A list of filtered game series.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getGameSeries(
         by filter: GameSeriesFilter
     ) async throws(AmiiboServiceError) -> [GameSeries] {
@@ -232,7 +253,10 @@ extension AmiiboLiveClient: APIClient {
             throw AmiiboServiceError.undocumented(statusCode)
         }
     }
-    
+
+    /// Gets the date when the data was last updated.
+    /// - Returns: A last updated date.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getLastUpdated() async throws(AmiiboServiceError) -> Date {
         let response: Operations.getLastUpdated.Output
 

Sources/AmiiboService/Public/Clients/AmiiboMockClient.swift

@@ -70,11 +70,16 @@ public struct AmiiboMockClient {
 }
 
 // MARK: - APIClient
+// TODO: Remove the documentation from the functions inside the following extension as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
 
 extension AmiiboMockClient: APIClient {
     
     // MARK: Functions
 
+    /// Gets a list of amiibo items based on a given filter.
+    /// - Parameter filter: A filter to remove unwanted items from the result.
+    /// - Returns: A list of filtered amiibo items.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getAmiibos(by filter: AmiiboFilter) async throws(AmiiboServiceError) -> [Amiibo] {
         try throwErrorIfExists()
 
@@ -84,7 +89,11 @@ extension AmiiboMockClient: APIClient {
         
         return amiibos
     }
-    
+
+    /// Gets a list of amiibo series based on a given filter.
+    /// - Parameter filter: A filter to remove unwanted items from the result.
+    /// - Returns: A list of filtered amiibo series.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getAmiiboSeries(by filter: AmiiboSeriesFilter) async throws(AmiiboServiceError) -> [AmiiboSeries] {
         try throwErrorIfExists()
 
@@ -94,7 +103,11 @@ extension AmiiboMockClient: APIClient {
         
         return amiiboSeries
     }
-    
+
+    /// Gets a list of amiibo types based on a given filter.
+    /// - Parameter filter: A filter to remove unwanted items from the result.
+    /// - Returns: A list of filtered amiibo types.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getAmiiboTypes(by filter: AmiiboTypeFilter) async throws(AmiiboServiceError) -> [AmiiboType] {
         try throwErrorIfExists()
 
@@ -104,7 +117,11 @@ extension AmiiboMockClient: APIClient {
         
         return amiiboTypes
     }
-    
+
+    /// Gets a list of game characters based on a given filter.
+    /// - Parameter filter: A filter to remove unwanted items from the result.
+    /// - Returns: A list of filtered game characters.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getGameCharacters(by filter: GameCharacterFilter) async throws(AmiiboServiceError) -> [GameCharacter] {
         try throwErrorIfExists()
 
@@ -114,7 +131,11 @@ extension AmiiboMockClient: APIClient {
         
         return gameCharacters
     }
-    
+
+    /// Gets a list of game series based on a given filter.
+    /// - Parameter filter: A filter to remove unwanted items from the result.
+    /// - Returns: A list of filtered game series.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getGameSeries(by filter: GameSeriesFilter) async throws(AmiiboServiceError) -> [GameSeries] {
         try throwErrorIfExists()
 
@@ -124,7 +145,10 @@ extension AmiiboMockClient: APIClient {
         
         return gameSeries
     }
-    
+
+    /// Gets the date when the data was last updated.
+    /// - Returns: A last updated date.
+    /// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
     public func getLastUpdated() async throws(AmiiboServiceError) -> Date {
         try throwErrorIfExists()
 

Sources/AmiiboService/Public/Enumerations/AmiiboClient.swift

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===
 
-/// A concrete representation of the types of client that a ``AmiiboService`` service can utilize.
+/// A representation of the types of client that a ``AmiiboService`` service can utilize.
 /// 
 /// > important: This enumeration has been defined as a way to avoid exposing the `APIClient` protocol outside the boundaries of this library.
 public enum AmiiboClient {

Sources/AmiiboService/Public/Filters/AmiiboSeriesFilter.swift

@@ -13,23 +13,33 @@
 /// A type that contains values to fine-tune a response when requesting amiibo series.
 public struct AmiiboSeriesFilter: KeyNameFilter {
     
+    // 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.
     public let key: String?
+
+    /// A name to return, if any.
     public let name: String?
     
     // MARK: Initializers
-    
+
+    /// Initializes this filter without key or name values.
     public init() {
         self.key = nil
         self.name = nil
     }
-    
+
+    /// Initializes this filter with a key value.
+    /// - Parameter key: A key to return.
     public init(key: String) {
         self.key = key
         self.name = nil
     }
-    
+
+    /// Initializes this filter with a name value.
+    /// - Parameter name: A name to return.
     public init(name: String) {
         self.key = nil
         self.name = name

Sources/AmiiboService/Public/Filters/AmiiboTypeFilter.swift

@@ -13,23 +13,33 @@
 /// A type that contains values to fine-tune a response when requesting amiibo types.
 public struct AmiiboTypeFilter: KeyNameFilter {
 
+    // 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.
     public let key: String?
+
+    /// A name to return, if any.
     public let name: String?
     
     // MARK: Initializers
-    
+
+    /// Initializes this filter without key or name values.
     public init() {
         self.key = nil
         self.name = nil
     }
-    
+
+    /// Initializes this filter with a key value.
+    /// - Parameter key: A key to return.
     public init(key: String) {
         self.key = key
         self.name = nil
     }
-    
+
+    /// Initializes this filter with a name value.
+    /// - Parameter name: A name to return.
     public init(name: String) {
         self.key = nil
         self.name = name

Sources/AmiiboService/Public/Filters/GameCharacterFilter.swift

@@ -13,23 +13,33 @@
 /// A type that contains values to fine-tune a response when requesting game characters.
 public struct GameCharacterFilter: KeyNameFilter {
     
-    // MARK: Properties
+    // 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.
     public let key: String?
+
+    /// A name to return, if any.
     public let name: String?
     
     // MARK: Initializers
-    
+
+    /// Initializes this filter without key or name values.
     public init() {
         self.key = nil
         self.name = nil
     }
-    
+
+    /// Initializes this filter with a key value.
+    /// - Parameter key: A key to return.
     public init(key: String) {
         self.key = key
         self.name = nil
     }
-    
+
+    /// Initializes this filter with a name value.
+    /// - Parameter name: A name to return.
     public init(name: String) {
         self.key = nil
         self.name = name

Sources/AmiiboService/Public/Filters/GameSeriesFilter.swift

@@ -13,23 +13,33 @@
 /// A type that contains values to fine-tune a response when requesting game series.
 public struct GameSeriesFilter: KeyNameFilter {
     
-    // MARK: Properties
+    // 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.
     public let key: String?
+
+    /// A name to return, if any.
     public let name: String?
     
     // MARK: Initializers
-    
+
+    /// Initializes this filter without key or name values.
     public init() {
         self.key = nil
         self.name = nil
     }
-    
+
+    /// Initializes this filter with a key value.
+    /// - Parameter key: A key to return.
     public init(key: String) {
         self.key = key
         self.name = nil
     }
-    
+
+    /// Initializes this filter with a name value.
+    /// - Parameter name: A name to return.
     public init(name: String) {
         self.key = nil
         self.name = name

Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Platform.swift

@@ -32,7 +32,7 @@ extension Amiibo {
         /// > important: In case no data is provided, then an instance of this model is not created.
         ///
         /// - Parameters:
-        ///   - `switch`: A list of `Switch` games related to an amiibo item, if any.
+        ///   - switch: A list of `Switch` games related to an amiibo item, if any.
         ///   - threeDS: A list of `3DS` games related to an amiibo item, if any.
         ///   - wiiU: A list of `WiiU` games related to an amiibo item, if any.
         init?(

Sources/AmiiboService/Public/Models/AmiiboSeries.swift

@@ -13,9 +13,14 @@
 /// A model that represents an amiibo series.
 public struct AmiiboSeries: KeyNameModel {
     
-    // MARK: Properties
+    // TODO: Remove the documentation from the properties of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
     
+    // MARK: Properties
+
+    /// A key.
     public let key: String
+
+    /// A name.
     public let name: String
     
     // MARK: Initializers

Sources/AmiiboService/Public/Models/AmiiboType.swift

@@ -12,10 +12,15 @@
 
 /// A model that represents an amiibo type.
 public struct AmiiboType: KeyNameModel {
-    
+
+    // TODO: Remove the documentation from the properties of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
+
     // MARK: Properties
-    
+
+    /// A key.
     public let key: String
+
+    /// A name.
     public let name: String
     
     // MARK: Initializers

Sources/AmiiboService/Public/Models/GameCharacter.swift

@@ -12,10 +12,15 @@
 
 /// A model that represents a game character.
 public struct GameCharacter: KeyNameModel {
-    
+
+    // TODO: Remove the documentation from the properties of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
+
     // MARK: Properties
-    
+
+    /// A key.
     public let key: String
+
+    /// A name.
     public let name: String
     
     // MARK: Initializers

Sources/AmiiboService/Public/Models/GameSeries.swift

@@ -12,10 +12,15 @@
 
 /// A model that represents a game series.
 public struct GameSeries: KeyNameModel {
-    
+
+    // TODO: Remove the documentation from the properties of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
+
     // MARK: Properties
-    
+
+    /// A key.
     public let key: String
+
+    /// A name.
     public let name: String
     
     // MARK: Initializers