Merge rust-bitcoin#5117: Add documentation for Witness::size panic

c3e1bdc Add documentation for panics during size calculations (Shing Him Ng)

Pull request description:

  Found while working on rust-bitcoin#5114


ACKs for top commit:
  apoelstra:
    ACK c3e1bdc; successfully ran local tests


Tree-SHA512: 3dbc4f42446146e9c5a4bd00bf39df1eab986df6e2fd5c7f8d86812fe833f2fbd5d2e2f76bb5839ad837807f57ec148840b46feb6f4a0e8aee2e2803d96ee181

Author: apoelstra

bitcoin/src/blockdata/block.rs

@@ -273,6 +273,10 @@ pub trait BlockCheckedExt: sealed::Sealed {
     ///
     /// > Total size is the block size in bytes with transactions serialized as described in BIP-0144,
     /// > including base data and witness data.
+    ///
+    /// # Panics
+    ///
+    /// If the size calculation overflows.
     fn total_size(&self) -> usize;
 
     /// Returns the coinbase transaction.
@@ -304,6 +308,9 @@ impl BlockCheckedExt for Block<Checked> {
         Weight::from_wu(wu.to_u64())
     }
 
+    /// # Panics
+    ///
+    /// If the size calculation overflows.
     fn total_size(&self) -> usize {
         let mut size = Header::SIZE;
 

bitcoin/src/blockdata/transaction.rs

@@ -286,12 +286,20 @@ pub trait TransactionExt: sealed::Sealed {
     /// Returns the base transaction size.
     ///
     /// > Base transaction size is the size of the transaction serialised with the witness data stripped.
+    ///
+    /// # Panics
+    ///
+    /// If the size calculation overflows.
     fn base_size(&self) -> usize;
 
     /// Returns the total transaction size.
     ///
     /// > Total transaction size is the transaction size in bytes serialized as described in BIP-0144,
     /// > including base data and witness data.
+    ///
+    /// # Panics
+    ///
+    /// If the size calculation overflows.
     fn total_size(&self) -> usize;
 
     /// Returns the "virtual size" (vsize) of this transaction.
@@ -385,6 +393,9 @@ impl TransactionExt for Transaction {
         Weight::from_wu(wu.to_u64())
     }
 
+    /// # Panics
+    ///
+    /// If the size calculation overflows.
     fn base_size(&self) -> usize {
         let mut size: usize = 4; // Serialized length of a u32 for the version number.
 
@@ -397,6 +408,9 @@ impl TransactionExt for Transaction {
         size + absolute::LockTime::SIZE
     }
 
+    /// # Panics
+    ///
+    /// If the size calculation overflows.
     #[inline]
     fn total_size(&self) -> usize {
         let mut size: usize = 4; // Serialized length of a u32 for the version number.

primitives/src/witness.rs

@@ -131,6 +131,10 @@ impl Witness {
     pub fn len(&self) -> usize { self.witness_elements }
 
     /// Returns the number of bytes this witness contributes to a transactions total size.
+    ///
+    /// # Panics
+    ///
+    /// If the size calculation overflows.
     pub fn size(&self) -> usize {
         let mut size: usize = 0;