From 333c8ab2975c91caf3054aa103eaac724684fa71 Mon Sep 17 00:00:00 2001
From: "Tobin C. Harding" <me@tobin.cc>
Date: Tue, 3 Sep 2024 08:25:41 +1000
Subject: [PATCH] Add additional docs to Witness

The `Witness` struct is non-trivial, in particular it is not immediately
obvious where and when the compact size encode value for each witness
element is stored.

Make an effort to improve the docs on `Witness` in relation to the
compact size encoded length of each witness element.
---
 bitcoin/src/blockdata/witness.rs | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/bitcoin/src/blockdata/witness.rs b/bitcoin/src/blockdata/witness.rs
index c5715a098..65a4db575 100644
--- a/bitcoin/src/blockdata/witness.rs
+++ b/bitcoin/src/blockdata/witness.rs
@@ -32,10 +32,12 @@ use crate::{Script, VarInt};
 pub struct Witness {
     /// Contains the witness `Vec<Vec<u8>>` serialization.
     ///
-    /// Does not include the initial varint indicating the number of elements, instead this is
-    /// stored stored in `witness_elements`. Concatenated onto the end of `content` is the index
-    /// area, this is a `4 * witness_elements` bytes area which stores the index of the start of
-    /// each witness item.
+    /// Does not include the initial varint indicating the number of elements. Each element however,
+    /// does include a varint indicating the element length. The number of elements is stored in
+    /// `witness_elements`.
+    ///
+    /// Concatenated onto the end of `content` is the index area. This is a `4 * witness_elements`
+    /// bytes area which stores the index of the start of each witness item.
     content: Vec<u8>,
 
     /// The number of elements in the witness.
@@ -227,6 +229,7 @@ fn resize_if_needed(vec: &mut Vec<u8>, required_len: usize) {
 }
 
 impl Encodable for Witness {
+    // `self.content` includes the varints so encoding here includes them, as expected.
     fn consensus_encode<W: Write + ?Sized>(&self, w: &mut W) -> Result<usize, io::Error> {
         let len = VarInt::from(self.witness_elements);
         len.consensus_encode(w)?;
@@ -517,6 +520,7 @@ impl serde::Serialize for Witness {
         let human_readable = serializer.is_human_readable();
         let mut seq = serializer.serialize_seq(Some(self.witness_elements))?;
 
+        // Note that the `Iter` strips the varints out when iterating.
         for elem in self.iter() {
             if human_readable {
                 seq.serialize_element(&crate::serde_utils::SerializeBytesAsHex(elem))?;