Merge rust-bitcoin/rust-bitcoin#1793: Comment predict_weight

dff757d7db Comment predict_weight (yancy)

Pull request description:

  I've been reading over the `predict_weight` function since it is one of the biggest challenges for coin-selection.  IE choosing inputs and constructing an optimal selection strategy requires predicting the weight to get the best selection.  It's great this work has been done but there are some things I don't understand well enough to comment.

  1) why are we looking at the size of VarInt struct here
  > let script_size = script_len + VarInt(script_len as u64).len()

  2) [predict_weight_internal](36500b4451/bitcoin/src/blockdata/transaction.rs (L1245)) has a bunch of magic numbers.  I'd like to be able to comment this as well but I don't fully understand that function.

  Also, `Transaction.rs` is a big file and it seems like all of the prediction stuff could be moved to a separate module or maybe a separate crate?

ACKs for top commit:
  tcharding:
    ACK dff757d7db
  Kixunil:
    ACK dff757d7db

Tree-SHA512: 8ffa16d500075d691528ce1819b9352a148af431889bebbd7cddcf470bd4e3048ec53a5e778bc3659e33d8c25b68422a93dac1d46b9489ff56f41d88d7f05433

bitcoin/src/blockdata/transaction.rs

@@ -1218,6 +1218,13 @@ where
     I: IntoIterator<Item = InputWeightPrediction>,
     O: IntoIterator<Item = usize>,
 {
+    // This fold() does three things:
+    // 1) Counts the inputs and returns the sum as `input_count`.
+    // 2) Sums all of the input weights and returns the sum as `partial_input_weight`
+    //    For every input: script_size * 4 + witness_size
+    //    Since script_size is non-witness data, it gets a 4x multiplier.
+    // 3) Counts the number of inputs that have a witness data and returns the count as
+    //    `num_inputs_with_witnesses`.
     let (input_count, partial_input_weight, inputs_with_witnesses) = inputs.into_iter().fold(
         (0, 0, 0),
         |(count, partial_input_weight, inputs_with_witnesses), prediction| {
@@ -1228,6 +1235,11 @@ where
             )
         },
     );
+
+    // This fold() does two things:
+    // 1) Counts the outputs and returns the sum as `output_count`.
+    // 2) Sums the output script sizes and returns the sum as `output_scripts_size`.
+    //    script_len + the length of a VarInt struct that stores the value of script_len
     let (output_count, output_scripts_size) = output_script_lens.into_iter().fold(
         (0, 0),
         |(output_count, total_scripts_size), script_len| {
@@ -1251,7 +1263,11 @@ const fn predict_weight_internal(
     output_count: usize,
     output_scripts_size: usize,
 ) -> Weight {
+    // Lengths of txid, index and sequence: (32, 4, 4).
+    // Multiply the lengths by 4 since the fields are all non-witness fields.
     let input_weight = partial_input_weight + input_count * 4 * (32 + 4 + 4);
+
+    // The value field of a TxOut is 8 bytes.
     let output_size = 8 * output_count + output_scripts_size;
     let non_input_size =
     // version: