Merge rust-bitcoin/rust-bitcoin#4394: chore: fix docs for `WitnessProgram` and extend test for P2A

8eeceed450 test: extend `valid_v1_witness_programs` test to include P2A (Luis Schwab)
647526dd1d chore: fix docs for `impl WitnessProgram` and P2A (Luis Schwab)

Pull request description:

  Closes #4124.

  This PR fixes documentation on `impl WitnessProgram` by replacing instances of `address` to `[WitnessProgram]`, adds punctuation and capitalization where it was lacking and extends the `valid_v1_witness_programs` test to include the P2A output.

ACKs for top commit:
  Kixunil:
    ACK 8eeceed450
  apoelstra:
    ACK 8eeceed450f7414c8a286a9e47b6f04b652b18ef; successfully ran local tests

Tree-SHA512: 6e62a8de7135da04d6330d2b5596a2cd19da8a849f8c8c892f53578a8690152b23facf58149d4139ae088f1ab297d3526094617c3549e688819e9b1f3688de8b

bitcoin/src/address/mod.rs

@@ -1567,7 +1567,7 @@ mod tests {
 
     #[test]
     fn pay_to_anchor_address_regtest() {
-        // Verify that p2a uses the expected address for regtest.
+        // Verify that P2A uses the expected address for regtest.
         // This test-vector is borrowed from the bitcoin source code.
         let address_str = "bcrt1pfeesnyr2tx";
 
@@ -1578,7 +1578,7 @@ mod tests {
         assert_eq!(address.to_string(), address_str);
 
         // Verify that the address is considered standard
-        // and that the output type is P2a
+        // and that the output type is P2A.
         assert!(address.is_spend_standard());
         assert_eq!(address.address_type(), Some(AddressType::P2a));
     }

bitcoin/src/address/script_pubkey.rs

@@ -198,7 +198,7 @@ pub(super) fn new_witness_program_unchecked<T: AsRef<PushBytes>>(
 ) -> ScriptBuf {
     let program = program.as_ref();
     debug_assert!(program.len() >= 2 && program.len() <= 40);
-    // In SegWit v0, the program must be either 20 (P2WPKH) bytes or 32 (P2WSH) bytes long
+    // In SegWit v0, the program must be either 20 bytes (P2WPKH) or 32 bytes (P2WSH) long.
     debug_assert!(version != WitnessVersion::V0 || program.len() == 20 || program.len() == 32);
     Builder::new().push_opcode(version.into()).push_slice(program).into_script()
 }

bitcoin/src/blockdata/script/witness_program.rs

@@ -70,7 +70,7 @@ impl WitnessProgram {
         WitnessProgram { version: WitnessVersion::V0, program: ArrayVec::from_slice(&program) }
     }
 
-    /// Constructs a new [`WitnessProgram`] from a 32 byte serialize Taproot xonly pubkey.
+    /// Constructs a new [`WitnessProgram`] from a 32 byte serialized Taproot x-only pubkey.
     fn new_p2tr(program: [u8; 32]) -> Self {
         WitnessProgram { version: WitnessVersion::V1, program: ArrayVec::from_slice(&program) }
     }
@@ -91,7 +91,10 @@ impl WitnessProgram {
         WitnessProgram::new_p2wsh(hash.to_byte_array())
     }
 
-    /// Constructs a new pay to Taproot address from an untweaked key.
+    /// Constructs a new [`WitnessProgram`] from an untweaked key for a P2TR output.
+    ///
+    /// This function applies BIP341 key-tweaking to the untweaked
+    /// key using the merkle root, if it's present.
     pub fn p2tr<C: Verification>(
         secp: &Secp256k1<C>,
         internal_key: UntweakedPublicKey,
@@ -102,13 +105,13 @@ impl WitnessProgram {
         WitnessProgram::new_p2tr(pubkey)
     }
 
-    /// Constructs a new pay to Taproot address from a pre-tweaked output key.
+    /// Constructs a new [`WitnessProgram`] from a tweaked key for a P2TR output.
     pub fn p2tr_tweaked(output_key: TweakedPublicKey) -> Self {
         let pubkey = output_key.to_inner().serialize();
         WitnessProgram::new_p2tr(pubkey)
     }
 
-    /// Constructs a new pay to anchor address
+    /// Constructs a new [`WitnessProgram`] for a P2A output.
     pub const fn p2a() -> Self {
         WitnessProgram { version: WitnessVersion::V1, program: ArrayVec::from_slice(&P2A_PROGRAM) }
     }
@@ -137,7 +140,7 @@ impl WitnessProgram {
     /// Returns true if this witness program is for a P2TR output.
     pub fn is_p2tr(&self) -> bool { self.version == WitnessVersion::V1 && self.program.len() == 32 }
 
-    /// Returns true if this is a pay to anchor output.
+    /// Returns true if this witness program is for a P2A output.
     pub fn is_p2a(&self) -> bool {
         self.version == WitnessVersion::V1 && self.program == P2A_PROGRAM
     }
@@ -221,6 +224,13 @@ mod tests {
         let arbitrary_bytes = [0x00; 32];
         assert!(WitnessProgram::new(WitnessVersion::V1, &arbitrary_bytes)
             .expect("valid witness program")
-            .is_p2tr());
+            .is_p2tr()
+        );
+
+        let p2a_bytes = [78, 115];
+        assert!(WitnessProgram::new(WitnessVersion::V1, &p2a_bytes)
+            .expect("valid witness program")
+            .is_p2a()
+        );
     }
 }