8
8
// licenses.
9
9
10
10
//! A very simple serialization framework which is used to serialize/deserialize messages as well
11
- //! as ChannelsManagers and ChannelMonitors.
11
+ //! as [`ChannelManager`]s and [`ChannelMonitor`]s.
12
+ //!
13
+ //! [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
14
+ //! [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
12
15
13
16
use crate :: prelude:: * ;
14
17
use crate :: io:: { self , Read , Seek , Write } ;
@@ -40,8 +43,8 @@ use crate::util::byte_utils::{be48_to_array, slice_to_be48};
40
43
/// serialization buffer size
41
44
pub const MAX_BUF_SIZE : usize = 64 * 1024 ;
42
45
43
- /// A simplified version of std::io::Write that exists largely for backwards compatibility.
44
- /// An impl is provided for any type that also impls std::io::Write.
46
+ /// A simplified version of [` std::io::Write`] that exists largely for backwards compatibility.
47
+ /// An impl is provided for any type that also impls [` std::io::Write`] .
45
48
///
46
49
/// (C-not exported) as we only export serialization to/from byte arrays instead
47
50
pub trait Writer {
@@ -175,21 +178,21 @@ impl<R: Read> Read for ReadTrackingReader<R> {
175
178
}
176
179
}
177
180
178
- /// A trait that various rust-lightning types implement allowing them to be written out to a Writer
181
+ /// A trait that various LDK types implement allowing them to be written out to a [` Writer`].
179
182
///
180
183
/// (C-not exported) as we only export serialization to/from byte arrays instead
181
184
pub trait Writeable {
182
- /// Writes self out to the given Writer
185
+ /// Writes ` self` out to the given [` Writer`].
183
186
fn write < W : Writer > ( & self , writer : & mut W ) -> Result < ( ) , io:: Error > ;
184
187
185
- /// Writes self out to a Vec<u8>
188
+ /// Writes ` self` out to a ` Vec<u8>`.
186
189
fn encode ( & self ) -> Vec < u8 > {
187
190
let mut msg = VecWriter ( Vec :: new ( ) ) ;
188
191
self . write ( & mut msg) . unwrap ( ) ;
189
192
msg. 0
190
193
}
191
194
192
- /// Writes self out to a Vec<u8>
195
+ /// Writes ` self` out to a ` Vec<u8>`.
193
196
#[ cfg( test) ]
194
197
fn encode_with_len ( & self ) -> Vec < u8 > {
195
198
let mut msg = VecWriter ( Vec :: new ( ) ) ;
@@ -215,64 +218,64 @@ impl<'a, T: Writeable> Writeable for &'a T {
215
218
fn write < W : Writer > ( & self , writer : & mut W ) -> Result < ( ) , io:: Error > { ( * self ) . write ( writer) }
216
219
}
217
220
218
- /// A trait that various rust-lightning types implement allowing them to be read in from a Read
221
+ /// A trait that various LDK types implement allowing them to be read in from a [` Read`].
219
222
///
220
223
/// (C-not exported) as we only export serialization to/from byte arrays instead
221
224
pub trait Readable
222
225
where Self : Sized
223
226
{
224
- /// Reads a Self in from the given Read
227
+ /// Reads a ` Self` in from the given [` Read`].
225
228
fn read < R : Read > ( reader : & mut R ) -> Result < Self , DecodeError > ;
226
229
}
227
230
228
- /// A trait that various rust-lightning types implement allowing them to be read in from a
229
- /// `Read + Seek`.
231
+ /// A trait that various LDK types implement allowing them to be read in from a
232
+ /// [ `Read`]` + `[` Seek`] .
230
233
pub ( crate ) trait SeekReadable where Self : Sized {
231
- /// Reads a Self in from the given Read
234
+ /// Reads a ` Self` in from the given [` Read`].
232
235
fn read < R : Read + Seek > ( reader : & mut R ) -> Result < Self , DecodeError > ;
233
236
}
234
237
235
- /// A trait that various higher-level rust-lightning types implement allowing them to be read in
236
- /// from a Read given some additional set of arguments which is required to deserialize.
238
+ /// A trait that various higher-level LDK types implement allowing them to be read in
239
+ /// from a [` Read`] given some additional set of arguments which is required to deserialize.
237
240
///
238
241
/// (C-not exported) as we only export serialization to/from byte arrays instead
239
242
pub trait ReadableArgs < P >
240
243
where Self : Sized
241
244
{
242
- /// Reads a Self in from the given Read
245
+ /// Reads a ` Self` in from the given [` Read`].
243
246
fn read < R : Read > ( reader : & mut R , params : P ) -> Result < Self , DecodeError > ;
244
247
}
245
248
246
- /// A std::io::Read that also provides the total bytes available to read.
249
+ /// A [` std::io::Read`] that also provides the total bytes available to be read.
247
250
pub ( crate ) trait LengthRead : Read {
248
- /// The total number of bytes available to read.
251
+ /// The total number of bytes available to be read.
249
252
fn total_bytes ( & self ) -> u64 ;
250
253
}
251
254
252
- /// A trait that various higher-level rust-lightning types implement allowing them to be read in
255
+ /// A trait that various higher-level LDK types implement allowing them to be read in
253
256
/// from a Read given some additional set of arguments which is required to deserialize, requiring
254
257
/// the implementer to provide the total length of the read.
255
258
pub ( crate ) trait LengthReadableArgs < P > where Self : Sized
256
259
{
257
- /// Reads a Self in from the given LengthRead
260
+ /// Reads a ` Self` in from the given [` LengthRead`].
258
261
fn read < R : LengthRead > ( reader : & mut R , params : P ) -> Result < Self , DecodeError > ;
259
262
}
260
263
261
- /// A trait that various higher-level rust-lightning types implement allowing them to be read in
262
- /// from a Read, requiring the implementer to provide the total length of the read.
264
+ /// A trait that various higher-level LDK types implement allowing them to be read in
265
+ /// from a [` Read`] , requiring the implementer to provide the total length of the read.
263
266
pub ( crate ) trait LengthReadable where Self : Sized
264
267
{
265
- /// Reads a Self in from the given LengthRead
268
+ /// Reads a ` Self` in from the given [` LengthRead`].
266
269
fn read < R : LengthRead > ( reader : & mut R ) -> Result < Self , DecodeError > ;
267
270
}
268
271
269
- /// A trait that various rust-lightning types implement allowing them to (maybe) be read in from a Read
272
+ /// A trait that various LDK types implement allowing them to (maybe) be read in from a [` Read`].
270
273
///
271
274
/// (C-not exported) as we only export serialization to/from byte arrays instead
272
275
pub trait MaybeReadable
273
276
where Self : Sized
274
277
{
275
- /// Reads a Self in from the given Read
278
+ /// Reads a ` Self` in from the given [` Read`].
276
279
fn read < R : Read > ( reader : & mut R ) -> Result < Option < Self > , DecodeError > ;
277
280
}
278
281
@@ -291,8 +294,8 @@ impl<T: Readable> Readable for OptionDeserWrapper<T> {
291
294
Ok ( Self ( Some ( Readable :: read ( reader) ?) ) )
292
295
}
293
296
}
294
- /// When handling default_values, we want to map the default-value T directly
295
- /// to a OptionDeserWrapper<T> in a way that works for `field: T = t;` as
297
+ /// When handling ` default_values` , we want to map the default-value T directly
298
+ /// to a ` OptionDeserWrapper<T>` in a way that works for `field: T = t;` as
296
299
/// well. Thus, we assume `Into<T> for T` does nothing and use that.
297
300
impl < T : Readable > From < T > for OptionDeserWrapper < T > {
298
301
fn from ( t : T ) -> OptionDeserWrapper < T > { OptionDeserWrapper ( Some ( t) ) }
@@ -314,7 +317,7 @@ impl Readable for U48 {
314
317
}
315
318
}
316
319
317
- /// Lightning TLV uses a custom variable-length integer called BigSize. It is similar to Bitcoin's
320
+ /// Lightning TLV uses a custom variable-length integer called ` BigSize` . It is similar to Bitcoin's
318
321
/// variable-length integers except that it is serialized in big-endian instead of little-endian.
319
322
///
320
323
/// Like Bitcoin's variable-length integer, it exhibits ambiguity in that certain values can be
@@ -380,7 +383,7 @@ impl Readable for BigSize {
380
383
381
384
/// In TLV we occasionally send fields which only consist of, or potentially end with, a
382
385
/// variable-length integer which is simply truncated by skipping high zero bytes. This type
383
- /// encapsulates such integers implementing Readable/ Writeable for them.
386
+ /// encapsulates such integers implementing [` Readable`]/[` Writeable`] for them.
384
387
#[ cfg_attr( test, derive( PartialEq , Eq , Debug ) ) ]
385
388
pub ( crate ) struct HighZeroBytesDroppedBigSize < T > ( pub T ) ;
386
389
@@ -532,7 +535,7 @@ impl Readable for [u16; 8] {
532
535
}
533
536
}
534
537
535
- /// For variable-length values within TLV record where the length is encoded as part of the record.
538
+ /// A type for variable-length values within TLV record where the length is encoded as part of the record.
536
539
/// Used to prevent encoding the length twice.
537
540
pub struct WithoutLength < T > ( pub T ) ;
538
541
@@ -1042,7 +1045,9 @@ impl Readable for String {
1042
1045
/// Only the character set and length will be validated.
1043
1046
/// The character set consists of ASCII alphanumeric characters, hyphens, and periods.
1044
1047
/// Its length is guaranteed to be representable by a single byte.
1045
- /// This serialization is used by BOLT 7 hostnames.
1048
+ /// This serialization is used by [`BOLT 7`] hostnames.
1049
+ ///
1050
+ /// [`BOLT 7`]: https://github.com/lightning/bolts/blob/master/07-routing-gossip.md
1046
1051
#[ derive( Clone , Debug , PartialEq , Eq ) ]
1047
1052
pub struct Hostname ( String ) ;
1048
1053
impl Hostname {
0 commit comments