From 028f687b21872b66a2907701e5a8e143d0f867a0 Mon Sep 17 00:00:00 2001
From: valued mammal <valuedmammal@protonmail.com>
Date: Fri, 6 Sep 2024 14:24:00 -0400
Subject: [PATCH] doc(wallet): Add docs to explain the lookahead

---
 crates/wallet/src/wallet/mod.rs    |  8 ++------
 crates/wallet/src/wallet/params.rs | 14 ++++++++++++--
 crates/wallet/src/wallet/signer.rs |  2 +-
 3 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/crates/wallet/src/wallet/mod.rs b/crates/wallet/src/wallet/mod.rs
index 9f12fac4e..347c9217a 100644
--- a/crates/wallet/src/wallet/mod.rs
+++ b/crates/wallet/src/wallet/mod.rs
@@ -313,7 +313,7 @@ impl Wallet {
     /// Additionally because this wallet has no internal (change) keychain, all methods that
     /// require a [`KeychainKind`] as input, e.g. [`reveal_next_address`] should only be called
     /// using the [`External`] variant. In most cases passing [`Internal`] is treated as the
-    /// equivalent of [`External`] but can lead to confusing results.
+    /// equivalent of [`External`] but this behavior must not be relied on.
     ///
     /// # Example
     ///
@@ -1070,8 +1070,6 @@ impl Wallet {
     /// **WARNING**: You must persist the changes resulting from one or more calls to this method
     /// if you need the inserted checkpoint data to be reloaded after closing the wallet.
     /// See [`Wallet::reveal_next_address`].
-    ///
-    /// [`commit`]: Self::commit
     pub fn insert_checkpoint(
         &mut self,
         block_id: BlockId,
@@ -2294,9 +2292,7 @@ impl Wallet {
     /// transactions related to your wallet into it.
     ///
     /// After applying updates you should persist the staged wallet changes. For an example of how
-    /// to persist staged wallet changes see [`Wallet::reveal_next_address`]. `
-    ///
-    /// [`commit`]: Self::commit
+    /// to persist staged wallet changes see [`Wallet::reveal_next_address`].
     #[cfg(feature = "std")]
     #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
     pub fn apply_update(&mut self, update: impl Into<Update>) -> Result<(), CannotConnectError> {
diff --git a/crates/wallet/src/wallet/params.rs b/crates/wallet/src/wallet/params.rs
index 7f4c8a36c..7cf3bdd27 100644
--- a/crates/wallet/src/wallet/params.rs
+++ b/crates/wallet/src/wallet/params.rs
@@ -107,7 +107,12 @@ impl CreateParams {
         self
     }
 
-    /// Use custom lookahead value.
+    /// Use a custom `lookahead` value.
+    ///
+    /// The `lookahead` defines a number of script pubkeys to derive over and above the last
+    /// revealed index. Without a lookahead the indexer will miss outputs you own when processing
+    /// transactions whose output script pubkeys lie beyond the last revealed index. In most cases
+    /// the default value [`DEFAULT_LOOKAHEAD`] is sufficient.
     pub fn lookahead(mut self, lookahead: u32) -> Self {
         self.lookahead = lookahead;
         self
@@ -211,7 +216,12 @@ impl LoadParams {
         self
     }
 
-    /// Use custom lookahead value.
+    /// Use a custom `lookahead` value.
+    ///
+    /// The `lookahead` defines a number of script pubkeys to derive over and above the last
+    /// revealed index. Without a lookahead the indexer will miss outputs you own when processing
+    /// transactions whose output script pubkeys lie beyond the last revealed index. In most cases
+    /// the default value [`DEFAULT_LOOKAHEAD`] is sufficient.
     pub fn lookahead(mut self, lookahead: u32) -> Self {
         self.lookahead = lookahead;
         self
diff --git a/crates/wallet/src/wallet/signer.rs b/crates/wallet/src/wallet/signer.rs
index 946ac20de..e08a43418 100644
--- a/crates/wallet/src/wallet/signer.rs
+++ b/crates/wallet/src/wallet/signer.rs
@@ -751,7 +751,7 @@ pub struct SignOptions {
     /// Whether the signer should trust the `witness_utxo`, if the `non_witness_utxo` hasn't been
     /// provided
     ///
-    /// Defaults to `false` to mitigate the "SegWit bug" which should trick the wallet into
+    /// Defaults to `false` to mitigate the "SegWit bug" which could trick the wallet into
     /// paying a fee larger than expected.
     ///
     /// Some wallets, especially if relatively old, might not provide the `non_witness_utxo` for