Improve DocC

Author: fpseverino

Sources/WalletOrders/OrderBuilder.swift

@@ -3,7 +3,7 @@ import Foundation
 @_spi(CMS) import X509
 import Zip
 
-/// A builder for generating order content bundles.
+/// A tool that generates pass content bundles.
 public struct OrderBuilder: Sendable {
     private let pemWWDRCertificate: String
     private let pemCertificate: String
@@ -18,6 +18,8 @@ public struct OrderBuilder: Sendable {
 
     /// Creates a new ``OrderBuilder``.
     ///
+    /// > Tip: Obtaining the three certificates files could be a bit tricky. You could get some guidance from [this guide](https://github.com/alexandercerutti/passkit-generator/wiki/Generating-Certificates) and [this video](https://www.youtube.com/watch?v=rJZdPoXHtzI). Those guides are for Wallet passes, but the process is similar for Wallet orders.
+    ///
     /// - Parameters:
     ///   - pemWWDRCertificate: Apple's WWDR.pem certificate in PEM format.
     ///   - pemCertificate: The PEM Certificate for signing orders.

Sources/WalletPasses/PassBuilder.swift

@@ -3,7 +3,7 @@ import Foundation
 @_spi(CMS) import X509
 import Zip
 
-/// A builder for generating pass content bundles.
+/// A tool that generates pass content bundles.
 public struct PassBuilder: Sendable {
     private let pemWWDRCertificate: String
     private let pemCertificate: String
@@ -18,6 +18,8 @@ public struct PassBuilder: Sendable {
 
     /// Creates a new ``PassBuilder``.
     ///
+    /// > Tip: Obtaining the three certificates files could be a bit tricky. You could get some guidance from [this guide](https://github.com/alexandercerutti/passkit-generator/wiki/Generating-Certificates) and [this video](https://www.youtube.com/watch?v=rJZdPoXHtzI).
+    ///
     /// - Parameters:
     ///   - pemWWDRCertificate: Apple's WWDR.pem certificate in PEM format.
     ///   - pemCertificate: The PEM Certificate for signing passes.
@@ -40,6 +42,8 @@ public struct PassBuilder: Sendable {
 
     /// Generates a signature for a given personalization token.
     ///
+    /// See <doc:PersonalizablePasses> for more information.
+    ///
     /// - Parameter data: The personalization token data to sign.
     ///
     /// - Returns: The generated signature as `Data`.
@@ -102,7 +106,7 @@ public struct PassBuilder: Sendable {
     /// - Parameters:
     ///   - pass: The pass to generate the content for.
     ///   - sourceFilesDirectoryPath: The path to the source files directory.
-    ///   - personalization: The personalization information for the pass.
+    ///   - personalization: The personalization information for the pass. See <doc:PersonalizablePasses> for more information.
     ///
     /// - Returns: The generated pass content as `Data`.
     public func build(

Sources/WalletPasses/WalletPasses.docc/PersonalizablePasses.md

@@ -6,7 +6,7 @@ Create and sign personalized passes for the Apple Wallet app.
 
 > Warning: This section is a work in progress. Testing is hard without access to the certificates required to develop this feature. If you have access to the entitlements, please help us implement this feature.
 
-Pass Personalization lets you create passes, referred to as personalizable passes, that prompt the user to provide personal information during signup that will be sent to your server.
+Pass Personalization lets you create passes, referred to as personalizable passes, that prompt the user to provide personal information during signup that will be sent to your server and used to update the pass.
 
 > Important: Making a pass personalizable, just like adding NFC to a pass, requires a special entitlement issued by Apple. Although accessing such entitlements is hard if you're not a big company, you can learn more in [Getting Started with Apple Wallet](https://developer.apple.com/wallet/get-started/).
 
@@ -24,12 +24,17 @@ A personalizable pass is just a standard pass package with the following additio
 To make a pass personalizable, you need to pass a ``PersonalizationJSON`` object to ``PassBuilder/build(pass:sourceFilesDirectoryPath:personalization:)``, and the source files directory must contain the `[email protected]` file.
 
 Once you've built the pass, you can distribute it like any other pass.
+
 The user will be prompted to provide the required personal information when they add the pass.
-Wallet will then send the user personal information to your server.
+
+Wallet will then send the user personal information to your server to be stored and used to update the pass, along with a personalization token that you have to sign and return to Wallet in the response.
+You can use the ``PassBuilder/signature(for:)`` to sign the personalization token.
+
 Immediately after that, the Wallet app will request the updated pass.
 
 > Important: The updated and personalized pass **must not** contain the `personalization.json` file.
 
 ## Topics
 
 - ``PersonalizationJSON``
+- ``PassBuilder/signature(for:)``