descriptor: Update the docs around spk method

A few of the descriptor types define a helper method `spk` to get the
scriptPukey. Currently the docs appear to be stale because
`Descriptor::script_pubkey` does not return an error.

Leave the API as it is and make an effort to document the code as it is
written.

Author: tcharding

src/descriptor/bare.rs

@@ -64,20 +64,20 @@ impl<Pk: MiniscriptKey> Bare<Pk> {
 }
 
 impl<Pk: MiniscriptKey + ToPublicKey> Bare<Pk> {
-    /// Obtain the corresponding script pubkey for this descriptor
-    /// Non failing verion of [`DescriptorTrait::script_pubkey`] for this descriptor
+    /// Obtains the corresponding script pubkey for this descriptor.
+    /// Called by [`DescriptorTrait::script_pubkey`] for this descriptor.
     pub fn spk(&self) -> Script {
         self.ms.encode()
     }
 
-    /// Obtain the underlying miniscript for this descriptor
-    /// Non failing verion of [`DescriptorTrait::explicit_script`] for this descriptor
+    /// Obtains the underlying miniscript for this descriptor.
+    /// Equivalent to [`DescriptorTrait::script_pubkey`] for this descriptor.
     pub fn inner_script(&self) -> Script {
         self.spk()
     }
 
-    /// Obtain the pre bip-340 signature script code for this descriptor
-    /// Non failing verion of [`DescriptorTrait::script_code`] for this descriptor
+    /// Obtains the pre bip-340 signature script code for this descriptor.
+    /// Equivalent to [`DescriptorTrait::script_pubkey`] for this descriptor.
     pub fn ecdsa_sighash_script_code(&self) -> Script {
         self.spk()
     }

src/descriptor/segwitv0.rs

@@ -359,23 +359,22 @@ impl<Pk: MiniscriptKey> Wpkh<Pk> {
 }
 
 impl<Pk: MiniscriptKey + ToPublicKey> Wpkh<Pk> {
-    /// Obtain the corresponding script pubkey for this descriptor
-    /// Non failing verion of [`DescriptorTrait::script_pubkey`] for this descriptor
+    /// Obtains the corresponding script pubkey for this descriptor.
+    /// Called by [`DescriptorTrait::script_pubkey`] for this descriptor.
     pub fn spk(&self) -> Script {
         let addr = Address::p2wpkh(&self.pk.to_public_key(), Network::Bitcoin)
             .expect("wpkh descriptors have compressed keys");
         addr.script_pubkey()
     }
 
-    /// Obtain the corresponding script pubkey for this descriptor
-    /// Non failing verion of [`DescriptorTrait::address`] for this descriptor
+    /// Obtains the [`Address`] for this descriptor.
     pub fn addr(&self, network: Network) -> Address {
-        Address::p2wpkh(&self.pk.to_public_key(), network)
+        bitcoin::Address::p2wpkh(&self.pk.to_public_key(), network)
             .expect("Rust Miniscript types don't allow uncompressed pks in segwit descriptors")
     }
 
-    /// Obtain the underlying miniscript for this descriptor
-    /// Non failing verion of [`DescriptorTrait::explicit_script`] for this descriptor
+    /// Obtains the underlying miniscript for this descriptor.
+    /// Equivalent to [`DescriptorTrait::script_pubkey`] for this descriptor.
     pub fn inner_script(&self) -> Script {
         self.spk()
     }

src/descriptor/sh.rs

@@ -208,8 +208,8 @@ impl<Pk: MiniscriptKey> Sh<Pk> {
 }
 
 impl<Pk: MiniscriptKey + ToPublicKey> Sh<Pk> {
-    /// Obtain the corresponding script pubkey for this descriptor
-    /// Non failing verion of [`DescriptorTrait::script_pubkey`] for this descriptor
+    /// Obtains the corresponding script pubkey for this descriptor.
+    /// Called by [`DescriptorTrait::script_pubkey`] for this descriptor.
     pub fn spk(&self) -> Script {
         match self.inner {
             ShInner::Wsh(ref wsh) => wsh.spk().to_p2sh(),
@@ -219,8 +219,7 @@ impl<Pk: MiniscriptKey + ToPublicKey> Sh<Pk> {
         }
     }
 
-    /// Obtain the corresponding script pubkey for this descriptor
-    /// Non failing verion of [`DescriptorTrait::address`] for this descriptor
+    /// Obtains the [`Address`] for this descriptor.
     pub fn addr(&self, network: Network) -> Address {
         match self.inner {
             ShInner::Wsh(ref wsh) => {
@@ -238,8 +237,7 @@ impl<Pk: MiniscriptKey + ToPublicKey> Sh<Pk> {
         }
     }
 
-    /// Obtain the underlying miniscript for this descriptor
-    /// Non failing verion of [`DescriptorTrait::explicit_script`] for this descriptor
+    /// Obtains the underlying miniscript for this descriptor.
     pub fn inner_script(&self) -> Script {
         match self.inner {
             ShInner::Wsh(ref wsh) => wsh.inner_script(),
@@ -249,12 +247,11 @@ impl<Pk: MiniscriptKey + ToPublicKey> Sh<Pk> {
         }
     }
 
-    /// Obtain the pre bip-340 signature script code for this descriptor
-    /// Non failing verion of [`DescriptorTrait::script_code`] for this descriptor
+    /// Obtain the pre bip-340 signature script code for this descriptor.
     pub fn ecdsa_sighash_script_code(&self) -> Script {
         match self.inner {
-            //     - For P2WSH witness program, if the witnessScript does not contain any `OP_CODESEPARATOR`,
-            //       the `scriptCode` is the `witnessScript` serialized as scripts inside CTxOut.
+            // For P2WSH witness program, if the witnessScript does not contain any `OP_CODESEPARATOR`,
+            // the `scriptCode` is the `witnessScript` serialized as scripts inside CTxOut.
             ShInner::Wsh(ref wsh) => wsh.ecdsa_sighash_script_code(),
             ShInner::SortedMulti(ref smv) => smv.encode(),
             ShInner::Wpkh(ref wpkh) => wpkh.ecdsa_sighash_script_code(),

src/descriptor/tr.rs

@@ -274,8 +274,8 @@ impl<Pk: MiniscriptKey> Tr<Pk> {
 }
 
 impl<Pk: MiniscriptKey + ToPublicKey> Tr<Pk> {
-    /// Obtain the corresponding script pubkey for this descriptor
-    /// Same as[`DescriptorTrait::script_pubkey`] for this descriptor
+    /// Obtains the corresponding script pubkey for this descriptor.
+    /// This is equivalent to [`DescriptorTrait::script_pubkey`] for this descriptor.
     pub fn spk(&self) -> Script {
         let output_key = self.spend_info().output_key();
         let builder = bitcoin::blockdata::script::Builder::new();
@@ -285,8 +285,7 @@ impl<Pk: MiniscriptKey + ToPublicKey> Tr<Pk> {
             .into_script()
     }
 
-    /// Obtain the corresponding script pubkey for this descriptor
-    /// Same as[`DescriptorTrait::address`] for this descriptor
+    /// Obtains the [`Address`] for this descriptor.
     pub fn addr(&self, network: Network) -> Result<Address, Error> {
         let spend_info = self.spend_info();
         Ok(Address::p2tr_tweaked(spend_info.output_key(), network))