more complete documentation

Author: extrawurst

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [0.2.1] - 2024-05-12
+
+### Added
+* proper rustdoc and readme with example
+
 ## [0.2.0] - 2024-05-09
 
 ### Changed

README.md

@@ -7,7 +7,7 @@
 [sh_crates]: https://img.shields.io/crates/v/bevy_ios_iap.svg
 [lk_crates]: https://crates.io/crates/bevy_ios_iap
 [sh_docs]: https://img.shields.io/docsrs/bevy_ios_iap
-[lk_docs]: https://docs.rs/bevy_ios_gamecenter/latest/bevy_ios_iap/
+[lk_docs]: https://docs.rs/bevy_ios_iap/latest/bevy_ios_iap/
 [sh_discord]: https://img.shields.io/discord/1176858176897953872?label=discord&color=5561E6
 [lk_discord]: https://discord.gg/rQNeEnMhus
 
@@ -65,7 +65,7 @@ or
 
 ```toml
 # always pin to the same exact version you also of the Swift package
-bevy_ios_iap = { version = "=0.2.0" }
+bevy_ios_iap = { version = "=0.2.1" }
 ```
 
 ### 3. Setup Plugin
@@ -79,6 +79,12 @@ app.add_plugins(IosIapPlugin::new(true));
 
 ```rust
 fn bevy_system() {
+    // If you set the plugin to manual init, this will register the 
+    // TranscactionObserver to listen to updates to any Transactions and trigger
+    // `IosIapEvents::Transaction` accordingly.
+    // Note: this will require the user to be logged in into their apple-id and popup a login dialog if not
+    bevy_ios_iap::init();
+
     // request product details, product IDs have to be explicitly provided
     // this will lead to a response: `IosIapEvents::Products`
     bevy_ios_iap::get_products(vec!["com.rustunit.zoolitaire.levelunlock".into()]);

bevy_ios_iap/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bevy_ios_iap"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"
 build = "build.rs"
 readme = "../README.md"

bevy_ios_iap/src/lib.rs

@@ -9,10 +9,16 @@ pub use methods::{
 pub use plugin::{IosIapEvents, IosIapPlugin};
 pub use transaction::IosIapTransaction;
 
+/// Expected event data in response to [`finish_transaction`] method call.
+///
+/// See Event [`IosIapEvents`]
 #[derive(Debug, Clone)]
 pub enum IosIapTransactionFinished {
+    /// Unknown Unfinished Transaction, maybe a concurrent process to finish it in the meantime?
     UnknownTransaction(u64),
+    /// Transaction successfully finished
     Finished(IosIapTransaction),
+    /// Some error occured
     Error(String),
 }
 
@@ -29,13 +35,21 @@ impl IosIapTransactionFinished {
     }
 }
 
+/// Expected event data in response to [`purchase`] method call.
+///
+/// See Event [`IosIapEvents`]
 #[derive(Debug, Clone)]
 pub enum IosIapPurchaseResult {
+    /// Purchase successful
     Success(IosIapTransaction),
+    /// User canceled the purchase
     Canceled(String),
+    /// The purchase is pending, and requires action from the customer. If the transaction completes,
+    /// it's available through the TransactionObserver registered via [`init`] and lead to [`IosIapEvents::Transaction`] calls.
     Pending(String),
-    /// Unknown / invalid product ID
+    /// Unknown / invalid product ID was used to trigger purchase
     Unknown(String),
+    /// Error occured
     Error(String),
 }
 
@@ -61,6 +75,12 @@ impl IosIapPurchaseResult {
     }
 }
 
+/// A cause of a purchase transaction, indicating whether it’s a customer’s purchase or
+/// an auto-renewable subscription renewal that the system initiates.
+///
+/// Part of [`IosIapTransaction`].
+///
+/// See <https://developer.apple.com/documentation/storekit/transaction/reason>
 #[derive(Debug, Clone)]
 pub enum IosIapTransactionReason {
     Renewal,
@@ -76,6 +96,11 @@ impl IosIapTransactionReason {
     }
 }
 
+/// The server environment that generates and signs the transaction.
+///
+/// Part of [`IosIapTransaction`].
+///
+/// See <https://developer.apple.com/documentation/storekit/transaction/3963920-environment>
 #[derive(Debug, Clone)]
 pub enum IosIapEnvironment {
     Production,
@@ -95,6 +120,11 @@ impl IosIapEnvironment {
     }
 }
 
+/// The App Store storefront associated with the transaction.
+///
+/// Part of [`IosIapTransaction`].
+///
+/// See <https://developer.apple.com/documentation/storekit/transaction/4193541-storefront>
 #[derive(Debug, Clone, Default)]
 pub struct IosIapStorefront {
     pub id: String,
@@ -107,6 +137,11 @@ impl IosIapStorefront {
     }
 }
 
+/// The type of the in-app purchase.
+///
+/// Part of [`IosIapTransaction`] and [`IosIapProduct`].
+///
+/// See <https://developer.apple.com/documentation/storekit/transaction/3749708-producttype>
 #[derive(Debug, Clone)]
 pub enum IosIapProductType {
     Consumable,
@@ -133,6 +168,11 @@ impl IosIapProductType {
     }
 }
 
+/// Expected event data in response to [`get_products`] method call.
+///
+/// See Event [`IosIapEvents`]
+///
+/// See <https://developer.apple.com/documentation/storekit/product>
 #[derive(Debug, Clone)]
 pub struct IosIapProduct {
     pub id: String,

bevy_ios_iap/src/methods.rs

@@ -3,44 +3,65 @@
 #[allow(unused_imports)]
 use crate::native;
 
+/// Registers for any updates on Transactions.
+/// Any such update will trigger: [`IosIapEvents::Transaction`][crate::IosIapEvents::Transaction]
+///
+/// See <https://developer.apple.com/documentation/storekit/transaction/3851206-updates>
 pub fn init() {
     #[cfg(target_os = "ios")]
     native::ios_iap_init();
 }
 
+/// Fetch Product Details. A list of Product IDs has to be provided.
+/// Expected to be confirmed with event: [`IosIapEvents::Products`][crate::IosIapEvents::Products]
+///
+/// See <https://developer.apple.com/documentation/storekit/product/3851116-products>
 pub fn get_products(products: Vec<String>) {
     #[cfg(target_os = "ios")]
     native::ios_iap_products(products);
 }
 
+/// Trigger a purchase flow. The product ID has to be provided
+/// Expected to be confirmed with event: [`IosIapEvents::Purchase`][crate::IosIapEvents::Purchase]
+///
+/// See <https://developer.apple.com/documentation/storekit/product/3791971-purchase>
 pub fn purchase(id: String) {
     #[cfg(target_os = "ios")]
     native::ios_iap_purchase(id);
 }
 
+/// Finishes a Transaction. Identify the Transaction with an ID.
+/// Apple expects us to call this only after the user got the Product granted so we can safely consider this purchase finished.
+/// Until the transaction is finished iOS will keep triggering it as soon as we register the
+/// TransactionObserver via the `init` call. See [`crate::init`].
+///
+/// Expected to be confirmed with event: [`IosIapEvents::TransactionFinished`][crate::IosIapEvents::TransactionFinished]
+///
+/// See <https://developer.apple.com/documentation/storekit/transaction/3749694-finish>
 pub fn finish_transaction(id: u64) {
     #[cfg(target_os = "ios")]
     native::ios_iap_transaction_finish(id);
 }
 
-/// > The transaction history includes consumable in-app purchases
-/// > that the app hasn’t finished by calling finish(). It doesn’t
-/// > include finished consumable products or finished non-renewing
-/// > subscriptions, repurchased non-consumable products or subscriptions,
-/// > or restored purchases.
+/// Quoted from Apple's docs: "A sequence that emits all the transactions for the user for your app."
+///
+/// Unlike [`crate::current_entitlements`] this will also return unfinished Transactions. Otherwise the result is the same.
+///
+/// Expected to be confirmed with event: [`IosIapEvents::AllTransactions`][crate::IosIapEvents::AllTransactions]
 ///
 /// See <https://developer.apple.com/documentation/storekit/transaction/3851203-all>
 pub fn all_transactions() {
     #[cfg(target_os = "ios")]
     native::ios_iap_transactions_all();
 }
 
-/// "A sequence of the latest transactions that entitle a user to in-app purchases and subscriptions."
+/// Quoted from Apple docs: "A sequence of the latest transactions that entitle a user to in-app purchases and subscriptions."
+///
+/// Ususally used for "RestorePurchases" functionality.
+/// Most importantly this will only included active subscriptions and non-consumables.
+/// Finished Transactions of Consumables will never appear again.
 ///
-/// > The current entitlements sequence emits the latest transaction for each product the user has an entitlement to, specifically:
-/// > A transaction for each non-consumable in-app purchase
-/// > The latest transaction for each auto-renewable subscription that has a Product.SubscriptionInfo.RenewalState state of subscribed or inGracePeriod
-/// > The latest transaction for each non-renewing subscription, including finished ones
+/// Expected to be confirmed with event: [`IosIapEvents::CurrentEntitlements`][crate::IosIapEvents::CurrentEntitlements]
 ///
 /// See <https://developer.apple.com/documentation/storekit/transaction/3851204-currententitlements>
 pub fn current_entitlements() {

bevy_ios_iap/src/plugin.rs

@@ -4,28 +4,32 @@ use bevy_ecs::prelude::*;
 use crate::transaction::IosIapTransaction;
 use crate::{IosIapProduct, IosIapPurchaseResult, IosIapTransactionFinished};
 
-///
+/// All events for communication from native iOS (Swift) side to Rust/Bevy
 #[derive(Event, Clone, Debug)]
 pub enum IosIapEvents {
+    /// Triggered by calls to [`get_products`][crate::get_products]
     Products(Vec<IosIapProduct>),
+    /// Triggered by calls to [`purchase`][crate::purchase]
     Purchase(IosIapPurchaseResult),
+    /// Triggered automatically by TransactionObserver registered by [`init`][crate::init]
+    /// for every update on any Transaction while app is running.
     Transaction(IosIapTransaction),
+    /// Triggered in response to calls to [`finish_transaction`][crate::finish_transaction]
     TransactionFinished(IosIapTransactionFinished),
-
-    /// async response to `all_transaction` request
+    /// Triggered in response to calls to [`all_transactions`][crate::all_transactions]
     AllTransactions(Vec<IosIapTransaction>),
-    /// async response to `current_entitlements` request
+    /// Triggered in response to calls to [`current_entitlements`][crate::current_entitlements]
     CurrentEntitlements(Vec<IosIapTransaction>),
 }
 
-///
+/// Bevy plugin to integrate access to iOS StoreKit2
 #[allow(dead_code)]
 pub struct IosIapPlugin {
     auto_init: bool,
 }
 
 impl IosIapPlugin {
-    ///
+    /// create plugin and define whether it will call [`init`] automatically right on startup.
     pub fn new(auto_init: bool) -> Self {
         Self { auto_init }
     }

bevy_ios_iap/src/transaction.rs

@@ -1,5 +1,10 @@
 use crate::{IosIapEnvironment, IosIapProductType, IosIapStorefront, IosIapTransactionReason};
 
+/// Representation of a Transaction.
+/// Mirrors the Transcation type in Apple's StoreKit2 closely.
+/// See official docs for more details on the individual fields.
+///
+/// See <https://developer.apple.com/documentation/storekit/transaction>
 #[derive(Debug, Clone)]
 pub struct IosIapTransaction {
     pub id: u64,