Merge bitcoindevkit#1596: doc(wallet): Add docs to explain the lookahead

028f687 doc(wallet): Add docs to explain the lookahead (valued mammal)

Pull request description:

  Adds clarifying language to `CreateParams` and `LoadParams` regarding the `lookahead` parameter. Commit 028f687 also includes some minor documentation fixes.

  If anyone is aware of any more documentation flaws that need attention I'm happy to add them here.

  cc bitcoindevkit#1540

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  * [x] I ran `cargo fmt` and `cargo clippy` before committing

ACKs for top commit:
  LagginTimes:
    ACK 028f687
  oleonardolima:
    ACK 028f687
  evanlinjin:
    ACK 028f687

Tree-SHA512: 971d09652948ed2e2dc86d255cfd18607d96b0806aa0e990190cd1d7035c6660ea2ac1092ef2c6c209e61920c0d4ff9d8c0a900bcc74a8662546d284fec3218f

crates/wallet/src/wallet/mod.rs

@@ -311,7 +311,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
     ///
@@ -1071,8 +1071,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,
@@ -2303,9 +2301,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> {

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

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