From 340808e820cc144c8b2756dd9c235fad1400ad76 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BF=97=E5=AE=87?= <hello@evanlinjin.me>
Date: Fri, 16 Aug 2024 04:11:20 +0000
Subject: [PATCH] docs(wallet): fixes/improvements for `persisted` and `params`
 types

---
 crates/wallet/src/wallet/params.rs    |  8 ++++----
 crates/wallet/src/wallet/persisted.rs | 20 +++++++++++++++-----
 2 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/crates/wallet/src/wallet/params.rs b/crates/wallet/src/wallet/params.rs
index d90124724..f91034002 100644
--- a/crates/wallet/src/wallet/params.rs
+++ b/crates/wallet/src/wallet/params.rs
@@ -109,7 +109,7 @@ impl CreateParams {
         self
     }
 
-    /// Create [`PersistedWallet`] with the given `Db`.
+    /// Create [`PersistedWallet`] with the given [`WalletPersister`].
     pub fn create_wallet<P>(
         self,
         persister: &mut P,
@@ -120,7 +120,7 @@ impl CreateParams {
         PersistedWallet::create(persister, self)
     }
 
-    /// Create [`PersistedWallet`] with the given async `Db`.
+    /// Create [`PersistedWallet`] with the given [`AsyncWalletPersister`].
     pub async fn create_wallet_async<P>(
         self,
         persister: &mut P,
@@ -220,7 +220,7 @@ impl LoadParams {
         self
     }
 
-    /// Load [`PersistedWallet`] with the given `persister`.
+    /// Load [`PersistedWallet`] with the given [`WalletPersister`].
     pub fn load_wallet<P>(
         self,
         persister: &mut P,
@@ -231,7 +231,7 @@ impl LoadParams {
         PersistedWallet::load(persister, self)
     }
 
-    /// Load [`PersistedWallet`] with the given async `persister`.
+    /// Load [`PersistedWallet`] with the given [`AsyncWalletPersister`].
     pub async fn load_wallet_async<P>(
         self,
         persister: &mut P,
diff --git a/crates/wallet/src/wallet/persisted.rs b/crates/wallet/src/wallet/persisted.rs
index 38d489e27..a8876e8e4 100644
--- a/crates/wallet/src/wallet/persisted.rs
+++ b/crates/wallet/src/wallet/persisted.rs
@@ -36,7 +36,10 @@ pub trait WalletPersister {
     /// data, return an empty changeset (using [`ChangeSet::default()`]).
     ///
     /// Error should only occur on database failure. Multiple calls to `initialize` should not
-    /// error. Calling [`persist`] before calling `initialize` should not error either.
+    /// error. Calling `initialize` inbetween calls to `persist` should not error.
+    ///
+    /// Calling [`persist`] before the `persister` is `initialize`d may error. However, some
+    /// persister implementations may NOT require initialization at all (and not error).
     ///
     /// [`persist`]: WalletPersister::persist
     fn initialize(persister: &mut Self) -> Result<ChangeSet, Self::Error>;
@@ -56,7 +59,7 @@ type FutureResult<'a, T, E> = Pin<Box<dyn Future<Output = Result<T, E>> + Send +
 /// For a blocking version, use [`WalletPersister`].
 ///
 /// Associated functions of this trait should not be called directly, and the trait is designed so
-/// that associated functions are hard to find (since they are not methods!). [`WalletPersister`] is
+/// that associated functions are hard to find (since they are not methods!). [`AsyncWalletPersister`] is
 /// used by [`PersistedWallet`] (a light wrapper around [`Wallet`]) which enforces some level of
 /// safety. Refer to [`PersistedWallet`] for more about the safety checks.
 pub trait AsyncWalletPersister {
@@ -66,7 +69,7 @@ pub trait AsyncWalletPersister {
     /// Initialize the `persister` and load all data.
     ///
     /// This is called by [`PersistedWallet::create_async`] and [`PersistedWallet::load_async`] to
-    /// ensure the [`WalletPersister`] is initialized and returns all data in the `persister`.
+    /// ensure the [`AsyncWalletPersister`] is initialized and returns all data in the `persister`.
     ///
     /// # Implementation Details
     ///
@@ -76,7 +79,10 @@ pub trait AsyncWalletPersister {
     /// data, return an empty changeset (using [`ChangeSet::default()`]).
     ///
     /// Error should only occur on database failure. Multiple calls to `initialize` should not
-    /// error. Calling [`persist`] before calling `initialize` should not error either.
+    /// error. Calling `initialize` inbetween calls to `persist` should not error.
+    ///
+    /// Calling [`persist`] before the `persister` is `initialize`d may error. However, some
+    /// persister implementations may NOT require initialization at all (and not error).
     ///
     /// [`persist`]: AsyncWalletPersister::persist
     fn initialize<'a>(persister: &'a mut Self) -> FutureResult<'a, ChangeSet, Self::Error>
@@ -171,6 +177,8 @@ impl<P: WalletPersister> PersistedWallet<P> {
 
     /// Persist staged changes of wallet into `persister`.
     ///
+    /// Returns whether any new changes were persisted.
+    ///
     /// If the `persister` errors, the staged changes will not be cleared.
     pub fn persist(&mut self, persister: &mut P) -> Result<bool, P::Error> {
         match self.inner.staged_mut() {
@@ -186,7 +194,7 @@ impl<P: WalletPersister> PersistedWallet<P> {
 
 /// Methods when `P` is an [`AsyncWalletPersister`].
 impl<P: AsyncWalletPersister> PersistedWallet<P> {
-    /// Create a new [`PersistedWallet`] witht the given async `persister` and `params`.
+    /// Create a new [`PersistedWallet`] with the given async `persister` and `params`.
     pub async fn create_async(
         persister: &mut P,
         params: CreateParams,
@@ -230,6 +238,8 @@ impl<P: AsyncWalletPersister> PersistedWallet<P> {
 
     /// Persist staged changes of wallet into an async `persister`.
     ///
+    /// Returns whether any new changes were persisted.
+    ///
     /// If the `persister` errors, the staged changes will not be cleared.
     pub async fn persist_async<'a>(&'a mut self, persister: &mut P) -> Result<bool, P::Error> {
         match self.inner.staged_mut() {