docs: document IWP function return limit and panic case

Document the newly added saturation point for internal arithmetic.

Author: yancyribbens

bitcoin/src/blockdata/transaction.rs

@@ -1126,12 +1126,18 @@ impl InputWeightPrediction {
 
     /// Computes the **signature weight** added to a transaction by an input with this weight prediction,
     /// not counting the prevout (txid, index), sequence, potential witness flag bytes or the witness count varint.
+    ///
+    /// This function's internal arithmetic saturates at u32::MAX, so the return value of this
+    /// function may be inaccurate for extremely large witness predictions.
     #[deprecated(since = "TBD", note = "use `InputWeightPrediction::witness_weight()` instead")]
     pub const fn weight(&self) -> Weight { Self::witness_weight(self) }
 
     /// Computes the signature, prevout (txid, index), and sequence weights of this weight
     /// prediction.
     ///
+    /// This function's internal arithmetic saturates at u32::MAX, so the return value of this
+    /// function may be inaccurate for extremely large witness predictions.
+    ///
     /// See also [`InputWeightPrediction::witness_weight`]
     pub const fn total_weight(&self) -> Weight {
         // `impl const Trait` is currently unavailable: rust/issues/67792
@@ -1142,6 +1148,9 @@ impl InputWeightPrediction {
 
     /// Computes the **signature weight** added to a transaction by an input with this weight prediction,
     /// not counting the prevout (txid, index), sequence, potential witness flag bytes or the witness count varint.
+    /// 
+    /// This function's internal arithmetic saturates at u32::MAX, so the return value of this
+    /// function may be inaccurate for extremely large witness predictions.
     ///
     /// See also [`InputWeightPrediction::total_weight`]
     pub const fn witness_weight(&self) -> Weight {