Improve the AssetProvider docs

Author: danielabrozzoni

src/plan.rs

@@ -34,15 +34,17 @@ use crate::{DefiniteDescriptorKey, DescriptorPublicKey, Error, MiniscriptKey, To
 
 /// Trait describing a present/missing lookup table for constructing witness templates
 ///
-/// This trait mirrors the [`Satisfier`] trait with the difference that instead of returning the
-/// item if it's present, it only returns a boolean to indicate its presence.
+/// This trait mirrors the [`Satisfier`] trait, with the difference that most methods just return a
+/// boolean indicating the item presence. The methods looking up keys return the key
+/// length, the methods looking up public key hashes return the public key, and a few other methods
+/// need to return the item itself.
 ///
 /// This trait is automatically implemented for every type that is also a satisfier, and simply
 /// proxies the queries to the satisfier and returns whether an item is available or not.
 ///
-/// All the methods have a default implementation that returns `false`.
+/// All the methods have a default implementation that returns `false` or `None`.
 pub trait AssetProvider<Pk: MiniscriptKey> {
-    /// Given a public key, look up an ECDSA signature with that key
+    /// Given a public key, look up an ECDSA signature with that key, return whether we found it
     fn provider_lookup_ecdsa_sig(&self, _: &Pk) -> bool {
         false
     }
@@ -52,7 +54,7 @@ pub trait AssetProvider<Pk: MiniscriptKey> {
         None
     }
 
-    /// Given a public key and a associated leaf hash, look up an schnorr signature with that key
+    /// Given a public key and a associated leaf hash, look up a schnorr signature with that key
     /// and return its size
     fn provider_lookup_tap_leaf_script_sig(&self, _: &Pk, _: &TapLeafHash) -> Option<usize> {
         None
@@ -96,22 +98,22 @@ pub trait AssetProvider<Pk: MiniscriptKey> {
         None
     }
 
-    /// Given a SHA256 hash, look up its preimage
+    /// Given a SHA256 hash, look up its preimage, return whether we found it
     fn provider_lookup_sha256(&self, _: &Pk::Sha256) -> bool {
         false
     }
 
-    /// Given a HASH256 hash, look up its preimage
+    /// Given a HASH256 hash, look up its preimage, return whether we found it
     fn provider_lookup_hash256(&self, _: &Pk::Hash256) -> bool {
         false
     }
 
-    /// Given a RIPEMD160 hash, look up its preimage
+    /// Given a RIPEMD160 hash, look up its preimage, return whether we found it
     fn provider_lookup_ripemd160(&self, _: &Pk::Ripemd160) -> bool {
         false
     }
 
-    /// Given a HASH160 hash, look up its preimage
+    /// Given a HASH160 hash, look up its preimage, return whether we found it
     fn provider_lookup_hash160(&self, _: &Pk::Hash160) -> bool {
         false
     }