Merge pull request #1950 from tnull/2023-01-fix-doc-warnings-and-nits

Fix doc warnings and doc cleanup in `msgs.rs`/`ser.rs`

Author: TheBlueMatt

lightning-invoice/src/lib.rs

@@ -297,7 +297,7 @@ pub struct RawInvoice {
 
 /// Data of the `RawInvoice` that is encoded in the human readable part
 ///
-/// (C-not exported) As we don't yet support Option<Enum>
+/// (C-not exported) As we don't yet support `Option<Enum>`
 #[derive(Eq, PartialEq, Debug, Clone, Hash)]
 pub struct RawHrp {
 	/// The currency deferred from the 3rd and 4th character of the bech32 transaction
@@ -806,6 +806,7 @@ impl SignedRawInvoice {
 ///
 /// The following example would extract the first B.
 ///
+/// ```ignore
 /// enum Enum {
 /// 	A(u8),
 /// 	B(u16)
@@ -814,6 +815,7 @@ impl SignedRawInvoice {
 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
 ///
 /// assert_eq!(find_extract!(elements.iter(), Enum::B(x), x), Some(3u16));
+/// ```
 macro_rules! find_extract {
 	($iter:expr, $enm:pat, $enm_var:ident) => {
 		find_all_extract!($iter, $enm, $enm_var).next()
@@ -825,6 +827,7 @@ macro_rules! find_extract {
 ///
 /// The following example would extract all A.
 ///
+/// ```ignore
 /// enum Enum {
 /// 	A(u8),
 /// 	B(u16)
@@ -836,6 +839,7 @@ macro_rules! find_extract {
 /// 	find_all_extract!(elements.iter(), Enum::A(x), x).collect::<Vec<u8>>(),
 /// 	vec![1u8, 2u8, 4u8]
 /// );
+/// ```
 macro_rules! find_all_extract {
 	($iter:expr, $enm:pat, $enm_var:ident) => {
 		$iter.filter_map(|tf| match *tf {
@@ -1276,7 +1280,7 @@ impl Invoice {
 		self.signed_invoice.amount_pico_btc().map(|v| v / 10)
 	}
 
-	/// Returns the amount if specified in the invoice as pico <currency>.
+	/// Returns the amount if specified in the invoice as pico BTC.
 	fn amount_pico_btc(&self) -> Option<u64> {
 		self.signed_invoice.amount_pico_btc()
 	}

lightning/src/ln/channel.rs

@@ -798,7 +798,7 @@ pub const MAX_CHAN_DUST_LIMIT_SATOSHIS: u64 = MAX_STD_OUTPUT_DUST_LIMIT_SATOSHIS
 /// In order to avoid having to concern ourselves with standardness during the closing process, we
 /// simply require our counterparty to use a dust limit which will leave any segwit output
 /// standard.
-/// See https://github.com/lightning/bolts/issues/905 for more details.
+/// See <https://github.com/lightning/bolts/issues/905> for more details.
 pub const MIN_CHAN_DUST_LIMIT_SATOSHIS: u64 = 354;
 
 // Just a reasonable implementation-specific safe lower bound, higher than the dust limit.

lightning/src/ln/msgs.rs

@@ -60,7 +60,7 @@ pub(crate) enum PendingOutboundPayment {
 	/// `PaymentPathFailed` events with `all_paths_failed` can be pending at once, confusing a
 	/// downstream event handler as to when a payment has actually failed.
 	///
-	/// (1) https://github.com/lightningdevkit/rust-lightning/issues/1164
+	/// (1) <https://github.com/lightningdevkit/rust-lightning/issues/1164>
 	Abandoned {
 		session_privs: HashSet<[u8; 32]>,
 		payment_hash: PaymentHash,

lightning/src/ln/outbound_payment.rs

@@ -644,7 +644,7 @@ impl<Descriptor: SocketDescriptor, RM: Deref, L: Deref> PeerManager<Descriptor,
 	}
 }
 
-/// A simple wrapper that optionally prints " from <pubkey>" for an optional pubkey.
+/// A simple wrapper that optionally prints ` from <pubkey>` for an optional pubkey.
 /// This works around `format!()` taking a reference to each argument, preventing
 /// `if let Some(node_id) = peer.their_node_id { format!(.., node_id) } else { .. }` from compiling
 /// due to lifetime errors.
@@ -656,8 +656,8 @@ impl core::fmt::Display for OptionalFromDebugger<'_> {
 }
 
 /// A function used to filter out local or private addresses
-/// https://www.iana.org./assignments/ipv4-address-space/ipv4-address-space.xhtml
-/// https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.xhtml
+/// <https://www.iana.org./assignments/ipv4-address-space/ipv4-address-space.xhtml>
+/// <https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.xhtml>
 fn filter_addresses(ip_address: Option<NetAddress>) -> Option<NetAddress> {
 	match ip_address{
 		// For IPv4 range 10.0.0.0 - 10.255.255.255 (10/8)

lightning/src/ln/peer_handler.rs

@@ -171,7 +171,7 @@ impl Default for ChannelHandshakeConfig {
 ///
 /// These limits are only applied to our counterparty's limits, not our own.
 ///
-/// Use 0/<type>::max_value() as appropriate to skip checking.
+/// Use 0/`<type>::max_value()` as appropriate to skip checking.
 ///
 /// Provides sane defaults for most configurations.
 ///

lightning/src/util/config.rs

@@ -8,7 +8,10 @@
 // licenses.
 
 //! A very simple serialization framework which is used to serialize/deserialize messages as well
-//! as ChannelsManagers and ChannelMonitors.
+//! as [`ChannelManager`]s and [`ChannelMonitor`]s.
+//!
+//! [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+//! [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
 
 use crate::prelude::*;
 use crate::io::{self, Read, Seek, Write};
@@ -40,8 +43,8 @@ use crate::util::byte_utils::{be48_to_array, slice_to_be48};
 /// serialization buffer size
 pub const MAX_BUF_SIZE: usize = 64 * 1024;
 
-/// A simplified version of std::io::Write that exists largely for backwards compatibility.
-/// An impl is provided for any type that also impls std::io::Write.
+/// A simplified version of [`std::io::Write`] that exists largely for backwards compatibility.
+/// An impl is provided for any type that also impls [`std::io::Write`].
 ///
 /// (C-not exported) as we only export serialization to/from byte arrays instead
 pub trait Writer {
@@ -175,21 +178,21 @@ impl<R: Read> Read for ReadTrackingReader<R> {
 	}
 }
 
-/// A trait that various rust-lightning types implement allowing them to be written out to a Writer
+/// A trait that various LDK types implement allowing them to be written out to a [`Writer`].
 ///
 /// (C-not exported) as we only export serialization to/from byte arrays instead
 pub trait Writeable {
-	/// Writes self out to the given Writer
+	/// Writes `self` out to the given [`Writer`].
 	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error>;
 
-	/// Writes self out to a Vec<u8>
+	/// Writes `self` out to a `Vec<u8>`.
 	fn encode(&self) -> Vec<u8> {
 		let mut msg = VecWriter(Vec::new());
 		self.write(&mut msg).unwrap();
 		msg.0
 	}
 
-	/// Writes self out to a Vec<u8>
+	/// Writes `self` out to a `Vec<u8>`.
 	#[cfg(test)]
 	fn encode_with_len(&self) -> Vec<u8> {
 		let mut msg = VecWriter(Vec::new());
@@ -215,64 +218,64 @@ impl<'a, T: Writeable> Writeable for &'a T {
 	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> { (*self).write(writer) }
 }
 
-/// A trait that various rust-lightning types implement allowing them to be read in from a Read
+/// A trait that various LDK types implement allowing them to be read in from a [`Read`].
 ///
 /// (C-not exported) as we only export serialization to/from byte arrays instead
 pub trait Readable
 	where Self: Sized
 {
-	/// Reads a Self in from the given Read
+	/// Reads a `Self` in from the given [`Read`].
 	fn read<R: Read>(reader: &mut R) -> Result<Self, DecodeError>;
 }
 
-/// A trait that various rust-lightning types implement allowing them to be read in from a
-/// `Read + Seek`.
+/// A trait that various LDK types implement allowing them to be read in from a
+/// [`Read`]` + `[`Seek`].
 pub(crate) trait SeekReadable where Self: Sized {
-	/// Reads a Self in from the given Read
+	/// Reads a `Self` in from the given [`Read`].
 	fn read<R: Read + Seek>(reader: &mut R) -> Result<Self, DecodeError>;
 }
 
-/// A trait that various higher-level rust-lightning types implement allowing them to be read in
-/// from a Read given some additional set of arguments which is required to deserialize.
+/// A trait that various higher-level LDK types implement allowing them to be read in
+/// from a [`Read`] given some additional set of arguments which is required to deserialize.
 ///
 /// (C-not exported) as we only export serialization to/from byte arrays instead
 pub trait ReadableArgs<P>
 	where Self: Sized
 {
-	/// Reads a Self in from the given Read
+	/// Reads a `Self` in from the given [`Read`].
 	fn read<R: Read>(reader: &mut R, params: P) -> Result<Self, DecodeError>;
 }
 
-/// A std::io::Read that also provides the total bytes available to read.
+/// A [`std::io::Read`] that also provides the total bytes available to be read.
 pub(crate) trait LengthRead: Read {
-	/// The total number of bytes available to read.
+	/// The total number of bytes available to be read.
 	fn total_bytes(&self) -> u64;
 }
 
-/// A trait that various higher-level rust-lightning types implement allowing them to be read in
+/// A trait that various higher-level LDK types implement allowing them to be read in
 /// from a Read given some additional set of arguments which is required to deserialize, requiring
 /// the implementer to provide the total length of the read.
 pub(crate) trait LengthReadableArgs<P> where Self: Sized
 {
-	/// Reads a Self in from the given LengthRead
+	/// Reads a `Self` in from the given [`LengthRead`].
 	fn read<R: LengthRead>(reader: &mut R, params: P) -> Result<Self, DecodeError>;
 }
 
-/// A trait that various higher-level rust-lightning types implement allowing them to be read in
-/// from a Read, requiring the implementer to provide the total length of the read.
+/// A trait that various higher-level LDK types implement allowing them to be read in
+/// from a [`Read`], requiring the implementer to provide the total length of the read.
 pub(crate) trait LengthReadable where Self: Sized
 {
-	/// Reads a Self in from the given LengthRead
+	/// Reads a `Self` in from the given [`LengthRead`].
 	fn read<R: LengthRead>(reader: &mut R) -> Result<Self, DecodeError>;
 }
 
-/// A trait that various rust-lightning types implement allowing them to (maybe) be read in from a Read
+/// A trait that various LDK types implement allowing them to (maybe) be read in from a [`Read`].
 ///
 /// (C-not exported) as we only export serialization to/from byte arrays instead
 pub trait MaybeReadable
 	where Self: Sized
 {
-	/// Reads a Self in from the given Read
+	/// Reads a `Self` in from the given [`Read`].
 	fn read<R: Read>(reader: &mut R) -> Result<Option<Self>, DecodeError>;
 }
 
@@ -291,8 +294,8 @@ impl<T: Readable> Readable for OptionDeserWrapper<T> {
 		Ok(Self(Some(Readable::read(reader)?)))
 	}
 }
-/// When handling default_values, we want to map the default-value T directly
-/// to a OptionDeserWrapper<T> in a way that works for `field: T = t;` as
+/// When handling `default_values`, we want to map the default-value T directly
+/// to a `OptionDeserWrapper<T>` in a way that works for `field: T = t;` as
 /// well. Thus, we assume `Into<T> for T` does nothing and use that.
 impl<T: Readable> From<T> for OptionDeserWrapper<T> {
 	fn from(t: T) -> OptionDeserWrapper<T> { OptionDeserWrapper(Some(t)) }
@@ -314,7 +317,7 @@ impl Readable for U48 {
 	}
 }
 
-/// Lightning TLV uses a custom variable-length integer called BigSize. It is similar to Bitcoin's
+/// Lightning TLV uses a custom variable-length integer called `BigSize`. It is similar to Bitcoin's
 /// variable-length integers except that it is serialized in big-endian instead of little-endian.
 ///
 /// Like Bitcoin's variable-length integer, it exhibits ambiguity in that certain values can be
@@ -380,7 +383,7 @@ impl Readable for BigSize {
 
 /// In TLV we occasionally send fields which only consist of, or potentially end with, a
 /// variable-length integer which is simply truncated by skipping high zero bytes. This type
-/// encapsulates such integers implementing Readable/Writeable for them.
+/// encapsulates such integers implementing [`Readable`]/[`Writeable`] for them.
 #[cfg_attr(test, derive(PartialEq, Eq, Debug))]
 pub(crate) struct HighZeroBytesDroppedBigSize<T>(pub T);
 
@@ -532,7 +535,7 @@ impl Readable for [u16; 8] {
 	}
 }
 
-/// For variable-length values within TLV record where the length is encoded as part of the record.
+/// A type for variable-length values within TLV record where the length is encoded as part of the record.
 /// Used to prevent encoding the length twice.
 pub struct WithoutLength<T>(pub T);
 
@@ -1042,7 +1045,9 @@ impl Readable for String {
 /// Only the character set and length will be validated.
 /// The character set consists of ASCII alphanumeric characters, hyphens, and periods.
 /// Its length is guaranteed to be representable by a single byte.
-/// This serialization is used by BOLT 7 hostnames.
+/// This serialization is used by [`BOLT 7`] hostnames.
+///
+/// [`BOLT 7`]: https://github.com/lightning/bolts/blob/master/07-routing-gossip.md
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Hostname(String);
 impl Hostname {