Skip to content

Commit 402aeb4

Browse files
committed
Add docs for exposed (de)serialization macros
1 parent 319de94 commit 402aeb4

File tree

1 file changed

+34
-9
lines changed

1 file changed

+34
-9
lines changed

lightning/src/util/ser_macros.rs

Lines changed: 34 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
//! Some macros that implement Readable/Writeable traits for lightning messages.
1111
//! They also handle serialization and deserialization of TLVs.
1212
13-
/// doc
13+
/// Implements serialization for a single TLV record.
1414
#[macro_export]
1515
macro_rules! encode_tlv {
1616
($stream: expr, $type: expr, $field: expr, (default_value, $default: expr)) => {
@@ -33,7 +33,7 @@ macro_rules! encode_tlv {
3333
};
3434
}
3535

36-
/// doc
36+
/// Implements the TLVs serialization part in a Writeable implementation of a struct.
3737
#[macro_export]
3838
macro_rules! encode_tlv_stream {
3939
($stream: expr, {$(($type: expr, $field: expr, $fieldty: tt)),* $(,)*}) => { {
@@ -102,7 +102,7 @@ macro_rules! encode_varint_length_prefixed_tlv {
102102
} }
103103
}
104104

105-
/// doc
105+
/// Asserts that the type of the last seen TLV is strictly less than the type of the TLV currently being processed.
106106
#[macro_export]
107107
macro_rules! check_tlv_order {
108108
($last_seen_type: expr, $typ: expr, $type: expr, $field: ident, (default_value, $default: expr)) => {{
@@ -130,7 +130,8 @@ macro_rules! check_tlv_order {
130130
}};
131131
}
132132

133-
/// doc
133+
/// Checks for required missing TLV records. If a required TLV is missing and has no default value,
134+
/// an error is returned.
134135
#[macro_export]
135136
macro_rules! check_missing_tlv {
136137
($last_seen_type: expr, $type: expr, $field: ident, (default_value, $default: expr)) => {{
@@ -158,7 +159,7 @@ macro_rules! check_missing_tlv {
158159
}};
159160
}
160161

161-
/// doc
162+
/// Implements deserialization for a single TLV record.
162163
#[macro_export]
163164
macro_rules! decode_tlv {
164165
($reader: expr, $field: ident, (default_value, $default: expr)) => {{
@@ -179,7 +180,7 @@ macro_rules! decode_tlv {
179180
}};
180181
}
181182

182-
/// doc
183+
/// Implements the TLVs deserialization part in a Readable implementation of a struct.
183184
#[macro_export]
184185
macro_rules! decode_tlv_stream {
185186
($stream: expr, {$(($type: expr, $field: ident, $fieldty: tt)),* $(,)*}) => { {
@@ -247,7 +248,30 @@ macro_rules! decode_tlv_stream {
247248
} }
248249
}
249250

250-
/// doc
251+
/// Implements Readable/Writeable for a struct. This macro also handles (de)serialization of TLV records.
252+
/// # Example
253+
/// ```
254+
/// use lightning::*;
255+
///
256+
/// #[derive(Debug)]
257+
/// pub struct LightningMessage {
258+
/// pub to: String,
259+
/// pub note: String,
260+
/// pub secret_number: u64,
261+
/// // TLV records
262+
/// pub nick_name: Option<String>,
263+
/// pub street_number: Option<u16>,
264+
/// }
265+
///
266+
/// impl_writeable_msg!(LightningMessage, {
267+
/// to,
268+
/// note,
269+
/// secret_number,
270+
/// }, {
271+
/// (1, nick_name, option),
272+
/// (3, street_number, option),
273+
/// });
274+
/// ```
251275
#[macro_export]
252276
macro_rules! impl_writeable_msg {
253277
($st:ident, {$($field:ident),* $(,)*}, {$(($type: expr, $tlvfield: ident, $fieldty: tt)),* $(,)*}) => {
@@ -272,7 +296,8 @@ macro_rules! impl_writeable_msg {
272296
}
273297
}
274298

275-
/// doc
299+
/// Implements Readable/Writeable for a struct. Note that this macro doesn't handle messages
300+
/// containing TLV records. If your message contains TLVs, use `impl_writeable_msg!` instead.
276301
#[macro_export]
277302
macro_rules! impl_writeable {
278303
($st:ident, {$($field:ident),*}) => {
@@ -373,7 +398,7 @@ macro_rules! init_tlv_based_struct_field {
373398
};
374399
}
375400

376-
/// doc
401+
/// Initializes the variables we are going to read the TLVs into.
377402
#[macro_export]
378403
macro_rules! init_tlv_field_var {
379404
($field: ident, (default_value, $default: expr)) => {

0 commit comments

Comments
 (0)