feat(sample): Fifth batch of sample app code

This also introduces documentation on multiple public models and functions.

Author: goncalo-frade-iohk

Apollo/Sources/ApolloImpl+Public.swift

@@ -100,13 +100,11 @@ returns random mnemonics nerver returns invalid mnemonics
         switch publicKey.curve {
         case "secp256k1":
             let verifier = JWTVerifier.es256(publicKey: publicKey.value)
-            let decoder = JWTDecoder.init(jwtVerifier: verifier)
-            let jwt = try decoder.decode(JWT<MyClaims>.self, fromString: jwk)
+            let decoder = JWTDecoder(jwtVerifier: verifier)
             return jwk
         default:
             let verifier = JWTVerifier.none
-            let decoder = JWTDecoder.init(jwtVerifier: verifier)
-            let jwt = try decoder.decode(JWT<MyClaims>.self, fromString: jwk)
+            let decoder = JWTDecoder(jwtVerifier: verifier)
             return jwk
         }
     }

Builders/Sources/PolluxBuilder.swift

@@ -1,5 +1,5 @@
-import Pollux
 import Domain
+import Pollux
 
 public struct PolluxBuilder {
     let castor: Castor

Domain/Sources/BBs/Apollo.swift

@@ -1,20 +1,100 @@
 import Foundation
 
 public protocol Apollo {
+    /// createRandomMnemonics creates a random set of mnemonic phrases that can be used as a seed for generating a private key.
+    ///
+    /// - Returns: An array of mnemonic phrases
     func createRandomMnemonics() -> [String]
+
+    /// createSeed takes in a set of mnemonics and a passphrase, and returns a seed object used to generate a private key.
+    /// This function may throw an error if the mnemonics or passphrase are invalid.
+    ///
+    /// - Parameters:
+    ///   - mnemonics: An array of mnemonic phrases
+    ///   - passphrase: A passphrase used to enhance the security of the seed
+    /// - Returns: A seed object
+    /// - Throws: An error if the mnemonics or passphrase are invalid
     func createSeed(mnemonics: [String], passphrase: String) throws -> Seed
+
+    /// createRandomSeed creates a random seed and a corresponding set of mnemonic phrases.
+    ///
+    /// - Returns: A tuple containing an array of mnemonic phrases and a seed object
     func createRandomSeed() -> (mnemonic: [String], seed: Seed)
+
+    /// createKeyPair creates a key pair (a private and public key) using a given seed and key curve.
+    ///
+    /// - Parameters:
+    ///   - seed: A seed object used to generate the key pair
+    ///   - curve: The key curve to use for generating the key pair
+    /// - Returns: A key pair object containing a private and public key
     func createKeyPair(seed: Seed, curve: KeyCurve) -> KeyPair
+
+    /// createKeyPair creates a key pair using a given seed and a specified private key. This function may throw an error if the private key is invalid.
+    ///
+    /// - Parameters:
+    ///   - seed: A seed object used to generate the key pair
+    ///   - privateKey: The private key to use for generating the key pair
+    /// - Returns: A key pair object containing a private and public key
+    /// - Throws: An error if the private key is invalid
     func createKeyPair(seed: Seed, privateKey: PrivateKey) throws -> KeyPair
+
+    /// compressedPublicKey compresses a given public key into a shorter, more efficient form.
+    ///
+    /// - Parameter publicKey: The public key to compress
+    /// - Returns: The compressed public key
     func compressedPublicKey(publicKey: PublicKey) -> CompressedPublicKey
+
+    /// compressedPublicKey decompresses a given compressed public key into its original form.
+    ///
+    /// - Parameter compressedData: The compressed public key data
+    /// - Returns: The decompressed public key
     func compressedPublicKey(compressedData: Data) -> CompressedPublicKey
+
+    /// signMessage signs a message using a given private key, returning the signature.
+    ///
+    /// - Parameters:
+    ///   - privateKey: The private key to use for signing the message
+    ///   - message: The message to sign, in binary data form
+    /// - Returns: The signature of the message
     func signMessage(privateKey: PrivateKey, message: Data) -> Signature
+
+    /// signMessage signs a message using a given private key, returning the signature. This function may throw an error if the message is invalid.
+    ///
+    /// - Parameters:
+    ///   - privateKey: The private key to use for signing the message
+    ///   - message: The message to sign, in string form
+    /// - Returns: The signature of the message
+    /// - Throws: An error if the message is invalid
     func signMessage(privateKey: PrivateKey, message: String) throws -> Signature
+
+    /// verifySignature verifies the authenticity of a signature using the corresponding public key, challenge, and signature. This function returns a boolean value indicating whether the signature is valid or not.
+    ///
+    /// - Parameters:
+    ///   - publicKey: The public key associated with the signature
+    ///   - challenge: The challenge used to generate the signature
+    ///   - signature: The signature to verify
+    /// - Returns: A boolean value indicating whether the signature is valid or not
     func verifySignature(
         publicKey: PublicKey,
         challenge: Data,
         signature: Signature
     ) -> Bool
+
+    /// getPrivateJWKJson converts a private key pair into a JSON Web Key (JWK) format with a given ID. This function may throw an error if the key pair is invalid.
+    ///
+    /// - Parameters:
+    ///   - id: The ID to use for the JWK
+    ///   - keyPair: The private key pair to convert to JWK format
+    /// - Returns: The private key pair in JWK format, as a string
+    /// - Throws: An error if the key pair is invalid
     func getPrivateJWKJson(id: String, keyPair: KeyPair) throws -> String
+
+    /// getPublicJWKJson converts a public key pair into a JSON Web Key (JWK) format with a given ID. This function may throw an error if the key pair is invalid.
+    ///
+    /// - Parameters:
+    ///   - id: The ID to use for the JWK
+    ///   - keyPair: The public key pair to convert to JWK format
+    /// - Returns: The public key pair in JWK format, as a string
+    /// - Throws: An error if the key pair is invalid
     func getPublicJWKJson(id: String, keyPair: KeyPair) throws -> String
 }

Domain/Sources/BBs/Castor.swift

@@ -1,32 +1,81 @@
 import Foundation
 
 public protocol Castor {
+    /// parseDID parses a string representation of a Decentralized Identifier (DID) into a DID object. This function may throw an error if the string is not a valid DID.
+    ///
+    /// - Parameter str: The string representation of the DID
+    /// - Returns: The DID object
+    /// - Throws: An error if the string is not a valid DID
     func parseDID(str: String) throws -> DID
+
+    /// createPrismDID creates a DID for a prism (a device or server that acts as a DID owner and controller) using a given master public key and list of services. This function may throw an error if the master public key or services are invalid.
+    ///
+    /// - Parameters:
+    ///   - masterPublicKey: The master public key of the prism
+    ///   - services: The list of services offered by the prism
+    /// - Returns: The DID of the prism
+    /// - Throws: An error if the master public key or services are invalid
     func createPrismDID(
         masterPublicKey: PublicKey,
         services: [DIDDocument.Service]
     ) throws -> DID
 
+    /// createPeerDID creates a DID for a peer (a device or server that acts as a DID subject) using given key agreement and authentication key pairs and a list of services. This function may throw an error if the key pairs or services are invalid.
+    ///
+    /// - Parameters:
+    ///   - keyAgreementKeyPair: The key pair used for key agreement (establishing secure communication between peers)
+    ///   - authenticationKeyPair: The key pair used for authentication (verifying the identity of a peer)
+    ///   - services: The list of services offered by the peer
+    /// - Returns: The DID of the peer
+    /// - Throws: An error if the key pairs or services are invalid
     func createPeerDID(
         keyAgreementKeyPair: KeyPair,
         authenticationKeyPair: KeyPair,
         services: [DIDDocument.Service]
     ) throws -> DID
 
+    /// resolveDID asynchronously resolves a DID to its corresponding DID Document. This function may throw an error if the DID is invalid or the document cannot be retrieved.
+    ///
+    /// - Parameter did: The DID to resolve
+    /// - Returns: The DID Document associated with the DID
+    /// - Throws: An error if the DID is invalid or the document cannot be retrieved
     func resolveDID(did: DID) async throws -> DIDDocument
 
+    /// verifySignature asynchronously verifies the authenticity of a signature using the corresponding DID, challenge, and signature data. This function returns a boolean value indicating whether the signature is valid or not. This function may throw an error if the DID or signature data are invalid.
+    ///
+    /// - Parameters:
+    ///   - did: The DID associated with the signature
+    ///   - challenge: The challenge used to generate the signature
+    ///   - signature: The signature data to verify
+    /// - Returns: A boolean value indicating whether the signature is valid or not
+    /// - Throws: An error if the DID or signature data are invalid
     func verifySignature(
         did: DID,
         challenge: Data,
         signature: Data
     ) async throws -> Bool
 
+    /// verifySignature verifies the authenticity of a signature using the corresponding DID Document, challenge, and signature data. This function returns a boolean value indicating whether the signature is valid or not. This function may throw an error if the DID Document or signature data are invalid.
+    ///
+    /// - Parameters:
+    ///   - document: The DID Document associated with the signature
+    ///   - challenge: The challenge used to generate the signature
+    ///   - signature: The signature data to verify
+    /// - Returns: A boolean value indicating whether the signature is valid or not
+    /// - Throws: An error if the DID Document or signature data are invalid
     func verifySignature(
         document: DIDDocument,
         challenge: Data,
         signature: Data
     ) throws -> Bool
 
+    /// getEcnumbasis generates a unique ECNUM basis string for a given DID and key pair. This function may throw an error if the DID or key pair are invalid.
+    ///
+    /// - Parameters:
+    ///   - did: The DID associated with the key pair
+    ///   - keyPair: The key pair to use for generating the ECNUM basis
+    /// - Returns: The ECNUM basis string
+    /// - Throws: An error if the DID or key pair are invalid
     func getEcnumbasis(did: DID, keyPair: KeyPair) throws -> String
 }
 

Domain/Sources/BBs/Mercury.swift

@@ -1,10 +1,33 @@
 import Foundation
 
 public protocol Mercury {
+    /// packMessage asynchronously packs a given message object into a string representation. This function may throw an error if the message object is invalid.
+    ///
+    /// - Parameter msg: The message object to pack
+    /// - Returns: The string representation of the packed message
+    /// - Throws: An error if the message object is invalid
     func packMessage(msg: Domain.Message) async throws -> String
+
+    /// unpackMessage asynchronously unpacks a given string representation of a message into a message object. This function may throw an error if the string is not a valid message representation.
+    ///
+    /// - Parameter msg: The string representation of the message to unpack
+    /// - Returns: The message object
+    /// - Throws: An error if the string is not a valid message representation
     func unpackMessage(msg: String) async throws -> Domain.Message
+
+    /// sendMessage asynchronously sends a given message and returns the response data. This function may throw an error if the message is invalid or the send operation fails.
+    ///
+    /// - Parameter msg: The message to send
+    /// - Returns: The response data
+    /// - Throws: An error if the message is invalid or the send operation fails
     @discardableResult
     func sendMessage(msg: Message) async throws -> Data?
+
+    /// sendMessageParseMessage asynchronously sends a given message and returns the response message object. This function may throw an error if the message is invalid, the send operation fails, or the response message is invalid.
+    ///
+    /// - Parameter msg: The message to send
+    /// - Returns: The response message object
+    /// - Throws: An error if the message is invalid, the send operation fails, or the response message is invalid
     @discardableResult
     func sendMessageParseMessage(msg: Message) async throws -> Message?
 }

Domain/Sources/Models/DID.swift

@@ -1,13 +1,21 @@
 import Foundation
 
+/// A type alias representing a DID method (a specific protocol or process used to resolve and manage DIDs) as a string.
 public typealias DIDMethod = String
+
+/// A type alias representing a DID method ID (a unique identifier within a DID method) as a string.
 public typealias DIDMethodId = String
 
-/// Represents a DID with ``DIDMethod`` and ``DIDMethodId``
-/// As specified in [w3 standards](https://www.w3.org/TR/did-core/#dfn-did-schemes)
+/// A DID is a unique and persistent identifier for a subject or object, such as a person, organization, or device. It is created and managed using a specific DID method, and consists of a schema, method, and method ID. The schema indicates the type of DID (e.g. "did"), the method indicates the specific protocol or process used to resolve and manage the DID (e.g. "prism"), and the method ID is a unique identifier within the DID method.
+/// As specified in the [W3C DID standards](https://www.w3.org/TR/did-core/#dfn-did-schemes).
 public struct DID: Equatable {
+    /// The schema of the DID (e.g. "did")
     public let schema: String
+
+    /// The method of the DID (e.g. "prism")
     public let method: DIDMethod
+
+    /// The method ID of the DID
     public let methodId: DIDMethodId
 
     /// Initializes a standard DID
@@ -26,6 +34,7 @@ public struct DID: Equatable {
     }
 
     /// String representation of this DID as specified in [w3 standards](https://www.w3.org/TR/did-core/#dfn-did-schemes)
+    /// This is a combination of the schema, method, and method ID, separated by colons (e.g. "did:prism:0xabc123").
     public var string: String { "\(schema):\(method):\(methodId)" }
 
     /// Simple initializer that receives a String and returns a DID