From d83390c63b997a8cae9c4ff050e119f1ae759101 Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Mon, 10 Jul 2023 22:24:31 +0000 Subject: [PATCH] Document some TLV write/read formats While we don't want to publicly document these and support them for downstream crates, documenting them internally is useful. --- lightning/src/util/ser_macros.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/lightning/src/util/ser_macros.rs b/lightning/src/util/ser_macros.rs index 90393f9d..710085e2 100644 --- a/lightning/src/util/ser_macros.rs +++ b/lightning/src/util/ser_macros.rs @@ -13,6 +13,21 @@ //! [`Readable`]: crate::util::ser::Readable //! [`Writeable`]: crate::util::ser::Writeable +// There are quite a few TLV serialization "types" which behave differently. We currently only +// publicly document the `optional` and `required` types, not supporting anything else publicly and +// changing them at will. +// +// Some of the other types include: +// * (default_value, $default) - reads optionally, reading $default if no TLV is present +// * (static_value, $value) - ignores any TLVs, always using $value +// * required_vec - reads into a Vec without a length prefix, failing if no TLV is present. +// * optional_vec - reads into an Option without a length prefix, continuing if no TLV is +// present. Writes from a Vec directly, only if any elements are present. Note +// that the struct deserialization macros return a Vec, not an Option. +// * upgradable_option - reads via MaybeReadable. +// * upgradable_required - reads via MaybeReadable, requiring a TLV be present but may return None +// if MaybeReadable::read() returns None. + /// Implements serialization for a single TLV record. /// This is exported for use by other exported macros, do not use directly. #[doc(hidden)] -- 2.30.2