Skip to content

Commit ce6bcf6

Browse files
authored
Merge pull request #1950 from tnull/2023-01-fix-doc-warnings-and-nits
Fix doc warnings and doc cleanup in `msgs.rs`/`ser.rs`
2 parents de783e0 + defa2f6 commit ce6bcf6

File tree

8 files changed

+351
-241
lines changed

8 files changed

+351
-241
lines changed

lightning-invoice/src/lib.rs

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -297,7 +297,7 @@ pub struct RawInvoice {
297297

298298
/// Data of the `RawInvoice` that is encoded in the human readable part
299299
///
300-
/// (C-not exported) As we don't yet support Option<Enum>
300+
/// (C-not exported) As we don't yet support `Option<Enum>`
301301
#[derive(Eq, PartialEq, Debug, Clone, Hash)]
302302
pub struct RawHrp {
303303
/// The currency deferred from the 3rd and 4th character of the bech32 transaction
@@ -806,6 +806,7 @@ impl SignedRawInvoice {
806806
///
807807
/// The following example would extract the first B.
808808
///
809+
/// ```ignore
809810
/// enum Enum {
810811
/// A(u8),
811812
/// B(u16)
@@ -814,6 +815,7 @@ impl SignedRawInvoice {
814815
/// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
815816
///
816817
/// assert_eq!(find_extract!(elements.iter(), Enum::B(x), x), Some(3u16));
818+
/// ```
817819
macro_rules! find_extract {
818820
($iter:expr, $enm:pat, $enm_var:ident) => {
819821
find_all_extract!($iter, $enm, $enm_var).next()
@@ -825,6 +827,7 @@ macro_rules! find_extract {
825827
///
826828
/// The following example would extract all A.
827829
///
830+
/// ```ignore
828831
/// enum Enum {
829832
/// A(u8),
830833
/// B(u16)
@@ -836,6 +839,7 @@ macro_rules! find_extract {
836839
/// find_all_extract!(elements.iter(), Enum::A(x), x).collect::<Vec<u8>>(),
837840
/// vec![1u8, 2u8, 4u8]
838841
/// );
842+
/// ```
839843
macro_rules! find_all_extract {
840844
($iter:expr, $enm:pat, $enm_var:ident) => {
841845
$iter.filter_map(|tf| match *tf {
@@ -1276,7 +1280,7 @@ impl Invoice {
12761280
self.signed_invoice.amount_pico_btc().map(|v| v / 10)
12771281
}
12781282

1279-
/// Returns the amount if specified in the invoice as pico <currency>.
1283+
/// Returns the amount if specified in the invoice as pico BTC.
12801284
fn amount_pico_btc(&self) -> Option<u64> {
12811285
self.signed_invoice.amount_pico_btc()
12821286
}

lightning/src/ln/channel.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -798,7 +798,7 @@ pub const MAX_CHAN_DUST_LIMIT_SATOSHIS: u64 = MAX_STD_OUTPUT_DUST_LIMIT_SATOSHIS
798798
/// In order to avoid having to concern ourselves with standardness during the closing process, we
799799
/// simply require our counterparty to use a dust limit which will leave any segwit output
800800
/// standard.
801-
/// See https://github.com/lightning/bolts/issues/905 for more details.
801+
/// See <https://github.com/lightning/bolts/issues/905> for more details.
802802
pub const MIN_CHAN_DUST_LIMIT_SATOSHIS: u64 = 354;
803803

804804
// Just a reasonable implementation-specific safe lower bound, higher than the dust limit.

lightning/src/ln/msgs.rs

Lines changed: 244 additions & 149 deletions
Large diffs are not rendered by default.

lightning/src/ln/outbound_payment.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ pub(crate) enum PendingOutboundPayment {
6060
/// `PaymentPathFailed` events with `all_paths_failed` can be pending at once, confusing a
6161
/// downstream event handler as to when a payment has actually failed.
6262
///
63-
/// (1) https://github.com/lightningdevkit/rust-lightning/issues/1164
63+
/// (1) <https://github.com/lightningdevkit/rust-lightning/issues/1164>
6464
Abandoned {
6565
session_privs: HashSet<[u8; 32]>,
6666
payment_hash: PaymentHash,

lightning/src/ln/peer_handler.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -644,7 +644,7 @@ impl<Descriptor: SocketDescriptor, RM: Deref, L: Deref> PeerManager<Descriptor,
644644
}
645645
}
646646

647-
/// A simple wrapper that optionally prints " from <pubkey>" for an optional pubkey.
647+
/// A simple wrapper that optionally prints ` from <pubkey>` for an optional pubkey.
648648
/// This works around `format!()` taking a reference to each argument, preventing
649649
/// `if let Some(node_id) = peer.their_node_id { format!(.., node_id) } else { .. }` from compiling
650650
/// due to lifetime errors.
@@ -656,8 +656,8 @@ impl core::fmt::Display for OptionalFromDebugger<'_> {
656656
}
657657

658658
/// A function used to filter out local or private addresses
659-
/// https://www.iana.org./assignments/ipv4-address-space/ipv4-address-space.xhtml
660-
/// https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.xhtml
659+
/// <https://www.iana.org./assignments/ipv4-address-space/ipv4-address-space.xhtml>
660+
/// <https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.xhtml>
661661
fn filter_addresses(ip_address: Option<NetAddress>) -> Option<NetAddress> {
662662
match ip_address{
663663
// For IPv4 range 10.0.0.0 - 10.255.255.255 (10/8)

lightning/src/util/config.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -171,7 +171,7 @@ impl Default for ChannelHandshakeConfig {
171171
///
172172
/// These limits are only applied to our counterparty's limits, not our own.
173173
///
174-
/// Use 0/<type>::max_value() as appropriate to skip checking.
174+
/// Use 0/`<type>::max_value()` as appropriate to skip checking.
175175
///
176176
/// Provides sane defaults for most configurations.
177177
///

lightning/src/util/ser.rs

Lines changed: 35 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,10 @@
88
// licenses.
99

1010
//! 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
1215
1316
use crate::prelude::*;
1417
use crate::io::{self, Read, Seek, Write};
@@ -40,8 +43,8 @@ use crate::util::byte_utils::{be48_to_array, slice_to_be48};
4043
/// serialization buffer size
4144
pub const MAX_BUF_SIZE: usize = 64 * 1024;
4245

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`].
4548
///
4649
/// (C-not exported) as we only export serialization to/from byte arrays instead
4750
pub trait Writer {
@@ -175,21 +178,21 @@ impl<R: Read> Read for ReadTrackingReader<R> {
175178
}
176179
}
177180

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`].
179182
///
180183
/// (C-not exported) as we only export serialization to/from byte arrays instead
181184
pub trait Writeable {
182-
/// Writes self out to the given Writer
185+
/// Writes `self` out to the given [`Writer`].
183186
fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error>;
184187

185-
/// Writes self out to a Vec<u8>
188+
/// Writes `self` out to a `Vec<u8>`.
186189
fn encode(&self) -> Vec<u8> {
187190
let mut msg = VecWriter(Vec::new());
188191
self.write(&mut msg).unwrap();
189192
msg.0
190193
}
191194

192-
/// Writes self out to a Vec<u8>
195+
/// Writes `self` out to a `Vec<u8>`.
193196
#[cfg(test)]
194197
fn encode_with_len(&self) -> Vec<u8> {
195198
let mut msg = VecWriter(Vec::new());
@@ -215,64 +218,64 @@ impl<'a, T: Writeable> Writeable for &'a T {
215218
fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> { (*self).write(writer) }
216219
}
217220

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`].
219222
///
220223
/// (C-not exported) as we only export serialization to/from byte arrays instead
221224
pub trait Readable
222225
where Self: Sized
223226
{
224-
/// Reads a Self in from the given Read
227+
/// Reads a `Self` in from the given [`Read`].
225228
fn read<R: Read>(reader: &mut R) -> Result<Self, DecodeError>;
226229
}
227230

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`].
230233
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`].
232235
fn read<R: Read + Seek>(reader: &mut R) -> Result<Self, DecodeError>;
233236
}
234237

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.
237240
///
238241
/// (C-not exported) as we only export serialization to/from byte arrays instead
239242
pub trait ReadableArgs<P>
240243
where Self: Sized
241244
{
242-
/// Reads a Self in from the given Read
245+
/// Reads a `Self` in from the given [`Read`].
243246
fn read<R: Read>(reader: &mut R, params: P) -> Result<Self, DecodeError>;
244247
}
245248

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.
247250
pub(crate) trait LengthRead: Read {
248-
/// The total number of bytes available to read.
251+
/// The total number of bytes available to be read.
249252
fn total_bytes(&self) -> u64;
250253
}
251254

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
253256
/// from a Read given some additional set of arguments which is required to deserialize, requiring
254257
/// the implementer to provide the total length of the read.
255258
pub(crate) trait LengthReadableArgs<P> where Self: Sized
256259
{
257-
/// Reads a Self in from the given LengthRead
260+
/// Reads a `Self` in from the given [`LengthRead`].
258261
fn read<R: LengthRead>(reader: &mut R, params: P) -> Result<Self, DecodeError>;
259262
}
260263

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.
263266
pub(crate) trait LengthReadable where Self: Sized
264267
{
265-
/// Reads a Self in from the given LengthRead
268+
/// Reads a `Self` in from the given [`LengthRead`].
266269
fn read<R: LengthRead>(reader: &mut R) -> Result<Self, DecodeError>;
267270
}
268271

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`].
270273
///
271274
/// (C-not exported) as we only export serialization to/from byte arrays instead
272275
pub trait MaybeReadable
273276
where Self: Sized
274277
{
275-
/// Reads a Self in from the given Read
278+
/// Reads a `Self` in from the given [`Read`].
276279
fn read<R: Read>(reader: &mut R) -> Result<Option<Self>, DecodeError>;
277280
}
278281

@@ -291,8 +294,8 @@ impl<T: Readable> Readable for OptionDeserWrapper<T> {
291294
Ok(Self(Some(Readable::read(reader)?)))
292295
}
293296
}
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
296299
/// well. Thus, we assume `Into<T> for T` does nothing and use that.
297300
impl<T: Readable> From<T> for OptionDeserWrapper<T> {
298301
fn from(t: T) -> OptionDeserWrapper<T> { OptionDeserWrapper(Some(t)) }
@@ -314,7 +317,7 @@ impl Readable for U48 {
314317
}
315318
}
316319

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
318321
/// variable-length integers except that it is serialized in big-endian instead of little-endian.
319322
///
320323
/// Like Bitcoin's variable-length integer, it exhibits ambiguity in that certain values can be
@@ -380,7 +383,7 @@ impl Readable for BigSize {
380383

381384
/// In TLV we occasionally send fields which only consist of, or potentially end with, a
382385
/// 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.
384387
#[cfg_attr(test, derive(PartialEq, Eq, Debug))]
385388
pub(crate) struct HighZeroBytesDroppedBigSize<T>(pub T);
386389

@@ -532,7 +535,7 @@ impl Readable for [u16; 8] {
532535
}
533536
}
534537

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.
536539
/// Used to prevent encoding the length twice.
537540
pub struct WithoutLength<T>(pub T);
538541

@@ -1042,7 +1045,9 @@ impl Readable for String {
10421045
/// Only the character set and length will be validated.
10431046
/// The character set consists of ASCII alphanumeric characters, hyphens, and periods.
10441047
/// 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
10461051
#[derive(Clone, Debug, PartialEq, Eq)]
10471052
pub struct Hostname(String);
10481053
impl Hostname {

0 commit comments

Comments
 (0)