10
10
//! Some macros that implement Readable/Writeable traits for lightning messages.
11
11
//! They also handle serialization and deserialization of TLVs.
12
12
13
- /// doc
13
+ /// Implements serialization for a single TLV record.
14
14
#[ macro_export]
15
15
macro_rules! encode_tlv {
16
16
( $stream: expr, $type: expr, $field: expr, ( default_value, $default: expr) ) => {
@@ -33,7 +33,7 @@ macro_rules! encode_tlv {
33
33
} ;
34
34
}
35
35
36
- /// doc
36
+ /// Implements the TLVs serialization part in a Writeable implementation of a struct.
37
37
#[ macro_export]
38
38
macro_rules! encode_tlv_stream {
39
39
( $stream: expr, { $( ( $type: expr, $field: expr, $fieldty: tt) ) ,* $( , ) * } ) => { {
@@ -102,7 +102,7 @@ macro_rules! encode_varint_length_prefixed_tlv {
102
102
} }
103
103
}
104
104
105
- /// doc
105
+ /// Asserts that the type of the last seen TLV is strictly less than the type of the TLV currently being processed.
106
106
#[ macro_export]
107
107
macro_rules! check_tlv_order {
108
108
( $last_seen_type: expr, $typ: expr, $type: expr, $field: ident, ( default_value, $default: expr) ) => { {
@@ -130,7 +130,8 @@ macro_rules! check_tlv_order {
130
130
} } ;
131
131
}
132
132
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.
134
135
#[ macro_export]
135
136
macro_rules! check_missing_tlv {
136
137
( $last_seen_type: expr, $type: expr, $field: ident, ( default_value, $default: expr) ) => { {
@@ -158,7 +159,7 @@ macro_rules! check_missing_tlv {
158
159
} } ;
159
160
}
160
161
161
- /// doc
162
+ /// Implements deserialization for a single TLV record.
162
163
#[ macro_export]
163
164
macro_rules! decode_tlv {
164
165
( $reader: expr, $field: ident, ( default_value, $default: expr) ) => { {
@@ -179,7 +180,7 @@ macro_rules! decode_tlv {
179
180
} } ;
180
181
}
181
182
182
- /// doc
183
+ /// Implements the TLVs deserialization part in a Readable implementation of a struct.
183
184
#[ macro_export]
184
185
macro_rules! decode_tlv_stream {
185
186
( $stream: expr, { $( ( $type: expr, $field: ident, $fieldty: tt) ) ,* $( , ) * } ) => { {
@@ -247,7 +248,30 @@ macro_rules! decode_tlv_stream {
247
248
} }
248
249
}
249
250
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
+ /// ```
251
275
#[ macro_export]
252
276
macro_rules! impl_writeable_msg {
253
277
( $st: ident, { $( $field: ident) ,* $( , ) * } , { $( ( $type: expr, $tlvfield: ident, $fieldty: tt) ) ,* $( , ) * } ) => {
@@ -272,7 +296,8 @@ macro_rules! impl_writeable_msg {
272
296
}
273
297
}
274
298
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.
276
301
#[ macro_export]
277
302
macro_rules! impl_writeable {
278
303
( $st: ident, { $( $field: ident) ,* } ) => {
@@ -373,7 +398,7 @@ macro_rules! init_tlv_based_struct_field {
373
398
} ;
374
399
}
375
400
376
- /// doc
401
+ /// Initializes the variables we are going to read the TLVs into.
377
402
#[ macro_export]
378
403
macro_rules! init_tlv_field_var {
379
404
( $field: ident, ( default_value, $default: expr) ) => {
0 commit comments