From: Valentine Wallace <vwallace@protonmail.com>
Date: Sat, 25 Feb 2023 21:03:43 +0000 (-0500)
Subject: ser_macros: Document behavior of upgradable_* variants
X-Git-Tag: v0.0.114-beta~3^2~3
X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=commitdiff_plain;h=34f8c396303f794fe5a3f7b3569a53fd70447777;p=rust-lightning

ser_macros: Document behavior of upgradable_* variants
---

diff --git a/lightning/src/util/ser_macros.rs b/lightning/src/util/ser_macros.rs
index 1f617de40..540856865 100644
--- a/lightning/src/util/ser_macros.rs
+++ b/lightning/src/util/ser_macros.rs
@@ -292,12 +292,19 @@ macro_rules! _decode_tlv {
 	($reader: expr, $field: ident, option) => {{
 		$field = Some($crate::util::ser::Readable::read(&mut $reader)?);
 	}};
+	// `upgradable_required` indicates we're reading a required TLV that may have been upgraded
+	// without backwards compat. We'll error if the field is missing, and return `Ok(None)` if the
+	// field is present but we can no longer understand it.
+	// Note that this variant can only be used within a `MaybeReadable` read.
 	($reader: expr, $field: ident, upgradable_required) => {{
 		$field = match $crate::util::ser::MaybeReadable::read(&mut $reader)? {
 			Some(res) => res,
 			_ => return Ok(None)
 		};
 	}};
+	// `upgradable_option` indicates we're reading an Option-al TLV that may have been upgraded
+	// without backwards compat. $field will be None if the TLV is missing or if the field is present
+	// but we can no longer understand it.
 	($reader: expr, $field: ident, upgradable_option) => {{
 		$field = $crate::util::ser::MaybeReadable::read(&mut $reader)?;
 	}};