Update docs

Author: danielsaidi

Sources/StoreKitPlus/Products/BasicProduct.swift

@@ -7,11 +7,10 @@
 
 import StoreKit
 
-/// This struct is a basic prroduct representation, that you
-/// can use to define your products with just an ID and name.
+/// This basic product representation can be used to refer to an App Store product
+/// with just its ID and name.
 ///
-/// The ``StoreContext`` is extended with more ways to fetch
-/// product information for a basic product.
+/// The ``StoreContext`` has ways to fetch product info for a basic product.
 public struct BasicProduct: Identifiable, ProductRepresentable, Sendable {
 
     /// Create a basic product representation.

Sources/StoreKitPlus/Products/Product+YearlySaving.swift

@@ -10,8 +10,8 @@ import StoreKit
 
 public extension Product {
 
-    /// Get a yearly savings in percentages when comparing a
-    /// yearly product with a monthy one.
+    /// Calculate a yearly savings percentage when comparing a yearly product
+    /// with a monthy one.
     ///
     /// - Returns: A raw 0-1 percentage.
     static func yearlySavingsPercentage(
@@ -24,8 +24,8 @@ public extension Product {
         )
     }
 
-    /// Get a yearly savings in percentages when comparing a
-    /// yearly price with a monthy one.
+    /// Calculate a yearly savings percentage when comparing a yearly product
+    /// price with a monthy one.
     ///
     /// - Returns: A raw 0-1 percentage.
     static func yearlySavingsPercentage(
@@ -38,8 +38,8 @@ public extension Product {
         return percentage
     }
 
-    /// Get a yearly savings in percentages when comparing a
-    /// yearly product with a monthy product variant.
+    /// Calculate a yearly savings percentage when comparing a yearly product
+    /// with a monthy one, and represent it as a 0-100 percentage.
     ///
     /// - Returns: A 0-100 (not 0-1) display percentage.
     static func yearlySavingsDisplayPercentage(
@@ -52,8 +52,8 @@ public extension Product {
         )
     }
 
-    /// Get a yearly savings in percentages when comparing a
-    /// yearly product with a monthy product variant.
+    /// Calculate a yearly savings percentage when comparing a yearly product
+    /// price with a monthy one, and represent it as a 0-100 percentage.
     ///
     /// - Returns: A 0-100 (not 0-1) display percentage.
     static func yearlySavingsDisplayPercentage(

Sources/StoreKitPlus/Products/ProductRepresentable.swift

@@ -8,15 +8,12 @@
 
 import Foundation
 
-/// This protocol can be implemented by types that should be
-/// able to represent a StoreKit product.
+/// This protocol can be implemented by types that represent a StoreKit product.
 ///
-/// This protocol can be used to define a local product that
-/// uses the same product ID as a real StoreKit product. The
-/// local product can then be used to provide any additional
-/// information, unit test product-based logic, present your
-/// products even if the app is unable to sync with StoreKit,
-/// e.g. when it is offline, etc.
+/// This protocol can be used to define a local product that uses the same product
+/// ID as a real StoreKit product. The local product can then provide any additional
+/// information, unit test product-based logic, present your products even if the app
+/// is unable to sync with StoreKit, e.g. when it is offline, etc.
 public protocol ProductRepresentable: Identifiable {
 
     var id: ProductID { get }

Sources/StoreKitPlus/Products/ProductUsp.swift

@@ -10,11 +10,9 @@ import SwiftUI
 
 /// This type defines a "unique selling point" for a product.
 ///
-/// A USP is a way to specify a list of reasons why a person
-/// should purchase your product.
-///
-/// A USP can be rendered with a ``ProductUsp/Label`` and an
-/// array of USPs with a ``ProductUsp/LabelStack``.
+/// Listing USPs is a way to tell people why they should purchase your product. A
+/// USP can be rendered with a ``ProductUsp/Label`` and an array of USPs
+/// can be rendered with a ``ProductUsp/LabelStack``.
 public struct ProductUsp {
 
     /// Create a custom USP.

Sources/StoreKitPlus/Services/StandardStoreService.swift

@@ -31,14 +31,13 @@ public extension StoreService where Self == StandardStoreService {
     }
 }
 
-/// This class implements the ``StoreService`` protocol, and
-/// can be used to integrate with StoreKit.
+/// This class can be used to integrate with StoreKit.
 ///
-/// You can use this service with a local product collection,
-/// by adding a StoreKit configuration file to the app.
+/// You can use this service with local products by adding a StoreKit configuration
+/// file to your app.
 ///
-/// You can use the two ``StoreService/standard(products:)``
-/// shorthands to easily create a standard service instance.
+/// You can use the ``StoreService/standard(products:)`` shorthands
+/// to easily create a standard service instance.
 open class StandardStoreService: StoreService {
 
     /// Create a service instance for the provided IDs.
@@ -134,8 +133,8 @@ open class StandardStoreService: StoreService {
         return result.isValid ? result : nil
     }
 
-    /// This function is called by the initializer, and will
-    /// fetch transaction updates and try to verify them.
+    /// This function is called by the initializer, and will fetch transaction updates
+    /// and try to verify them.
     open func updateTransactionsOnLaunch() {
         Task.detached {
             for await result in Transaction.updates {

Sources/StoreKitPlus/Services/StoreService.swift

@@ -8,13 +8,13 @@
 
 import StoreKit
 
-/// This protocol can be implemented by any classes that can
-/// be used to fetch and purchase products, restore purchase
-/// information, etc.
+/// This protocol can be implemented by types that can fetch product information,
+/// purchase products, restore purchase information, etc.
 ///
-/// Although some operations can be performed directly using
-/// StoreKit like `Product.products(for:)`, the service lets
-/// you customize any part of the StoreKit integration.
+/// Although many operations can be performed by using the StoreKit APIs directly,
+/// like using `Product.products(for:)` to fetch products, a store service
+/// can be used as a layer between the app and StoreKit, and can also be used to
+/// customize or mock the integration, e.g. in tests.
 public protocol StoreService {
 
     /// Get all available products.

Sources/StoreKitPlus/StoreContext+Products.swift

@@ -22,8 +22,8 @@ public extension StoreContext {
 
     /// Get a product with a certain ID.
     ///
-    /// This function will only return a matching product if
-    /// the ``products`` array has been synced with StoreKit.
+    /// This will only return a matching product if the ``products`` array has
+    /// been synced with StoreKit.
     ///
     /// - Parameters:
     ///   - id: The ID of the product to fetch.

Sources/StoreKitPlus/StoreContext.swift

@@ -8,26 +8,17 @@
 
 import StoreKit
 
-/// This observable class can manage store-based information
-/// in a way that makes it observable.
+/// This observable class can manage store-based state in an observable way.
 ///
-/// You can use the ``StandardStoreService`` to sync product
-/// info with this context, which will update the ``products``
-/// array with matching products.
+/// You can use the ``StandardStoreService`` to sync product information
+/// with a context instance when performing certain operations.
 ///
-/// Since StoreKit `Product` isn't `Codable`, the ``products``
-/// array is not permanently persisted, which means that the
-/// property will reset when the app is restarted.
-///
-/// Due to this, there's also a ``productIds`` property that
-/// is permanently persisted. It gives you the option to map
-/// ``productIds`` to local product representations whenever
-/// the app can't access StoreKit.
-///
-/// However, a StoreKit `Product` value is needed to perform
-/// a purchase. If your app fails to fetch products, e.g. if
-/// it's offline, you should show a spinner or an alert that
-/// informs your users that your products can't be retrieved.
+/// Since StoreKit `Product` isn't `Codable`, the ``products`` array isn't
+/// permanently persisted. This means that it will reset when the app is restarted.
+/// Due to this, there's also a ``productIds`` property that *is* permanently
+/// persisted. This gives you an option to map ``productIds`` to local product
+/// representations whenever the app can't access StoreKit. However, note that a
+/// StoreKit `Product` is needed to perform a purchase.
 public class StoreContext: ObservableObject, @unchecked Sendable {
 
     /// Create a context instance.
@@ -41,49 +32,23 @@ public class StoreContext: ObservableObject, @unchecked Sendable {
     }
 
     /// A list of synced products.
-    ///
-    /// You can use this property to keep track of a product
-    /// collection that has been fetched from StoreKit.
-    ///
-    /// Since `Product` isn't `Codable`, this property can't
-    /// be persisted and must be reloaded on app launch.
     @Published
     public var products: [Product] {
         didSet { productIds = products.map { $0.id} }
     }
 
-    /// A list of synced products IDs.
-    ///
-    /// You can use this property to keep track of a product
-    /// collection that has been fetched from StoreKit.
-    ///
-    /// This property is persisted, which means that you can
-    /// map these IDs to a local product representation when
-    /// a StoreKit request fails.
+    /// A persisted list of synced products IDs.
     @Published
     public internal(set) var productIds: [String] = [] {
         willSet { persistedProductIds = newValue }
     }
 
     /// A list of active purchase transactions.
-    ///
-    /// You can use this property to keep track of purchased
-    /// products that has been fetched from StoreKit.
-    ///
-    /// Since `Transaction` isn't `Codable` this property is
-    /// not persisted and must be reloaded on app launch.
     public var purchaseTransactions: [Transaction] = [] {
         didSet { purchasedProductIds = purchaseTransactions.map { $0.productID } }
     }
 
     /// A list of purchased product IDs.
-    ///
-    /// You can use this property to keep track of purchased
-    /// products that has been fetched from StoreKit.
-    ///
-    /// This property is persisted, which means that you can
-    /// map these IDs to a local product representation when
-    /// a StoreKit request fails.
     @Published
     public internal(set) var purchasedProductIds: [String] = [] {
         willSet { persistedPurchasedProductIds = newValue }

Sources/StoreKitPlus/Validation/ValidatableTransaction.swift

@@ -8,11 +8,7 @@
 
 import StoreKit
 
-/// This protocol can be implemented by any transaction that
-/// can be validated.
-///
-/// Valid transactions have no revocation date and also have
-/// expired expiration date.
+/// This protocol can be implemented by any transaction that can be validated.
 public protocol ValidatableTransaction {
 
     /// The date, if any, when the transaction expired.
@@ -28,8 +24,7 @@ public extension ValidatableTransaction {
 
     /// Whether or not the transaction is valid.
     ///
-    /// A valid transaction has no revocation date, and also
-    /// has no expiration date that has passed.
+    /// A valid transaction has no revocation date, and no past expiration date.
     var isValid: Bool {
         if revocationDate != nil { return false }
         guard let date = expirationDate else { return true }