From: Elias Rohrer Date: Fri, 13 Jan 2023 15:18:26 +0000 (-0600) Subject: Fix doc warnings and cleanup in `msgs.rs` X-Git-Tag: v0.0.114-beta~62^2~3 X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=commitdiff_plain;h=7eac8977467c06fb5746cb2ec0789ce1f37e02fa;p=rust-lightning Fix doc warnings and cleanup in `msgs.rs` --- diff --git a/lightning/src/ln/msgs.rs b/lightning/src/ln/msgs.rs index 399feaf67..278352845 100644 --- a/lightning/src/ln/msgs.rs +++ b/lightning/src/ln/msgs.rs @@ -12,12 +12,12 @@ //! For a normal node you probably don't need to use anything here, however, if you wish to split a //! node into an internet-facing route/message socket handling daemon and a separate daemon (or //! server entirely) which handles only channel-related messages you may wish to implement -//! ChannelMessageHandler yourself and use it to re-serialize messages and pass them across +//! [`ChannelMessageHandler`] yourself and use it to re-serialize messages and pass them across //! daemons/servers. //! //! Note that if you go with such an architecture (instead of passing raw socket events to a //! non-internet-facing system) you trust the frontend internet-facing system to not lie about the -//! source node_id of the message, however this does allow you to significantly reduce bandwidth +//! source `node_id` of the message, however this does allow you to significantly reduce bandwidth //! between the systems as routing messages can represent a significant chunk of bandwidth usage //! (especially for non-channel-publicly-announcing nodes). As an alternate design which avoids //! this issue, if you have sufficient bidirectional bandwidth between your systems, you may send @@ -53,37 +53,46 @@ pub(crate) const MAX_VALUE_MSAT: u64 = 21_000_000_0000_0000_000; #[derive(Clone, Debug, PartialEq, Eq)] pub enum DecodeError { /// A version byte specified something we don't know how to handle. - /// Includes unknown realm byte in an OnionHopData packet + /// + /// Includes unknown realm byte in an onion hop data packet. UnknownVersion, - /// Unknown feature mandating we fail to parse message (eg TLV with an even, unknown type) + /// Unknown feature mandating we fail to parse message (e.g., TLV with an even, unknown type) UnknownRequiredFeature, - /// Value was invalid, eg a byte which was supposed to be a bool was something other than a 0 + /// Value was invalid. + /// + /// For example, a byte which was supposed to be a bool was something other than a 0 /// or 1, a public key/private key/signature was invalid, text wasn't UTF-8, TLV was - /// syntactically incorrect, etc + /// syntactically incorrect, etc. InvalidValue, - /// Buffer too short + /// The buffer to be read was too short. ShortRead, - /// A length descriptor in the packet didn't describe the later data correctly + /// A length descriptor in the packet didn't describe the later data correctly. BadLengthDescriptor, - /// Error from std::io + /// Error from [`std::io`]. Io(io::ErrorKind), /// The message included zlib-compressed values, which we don't support. UnsupportedCompression, } -/// An init message to be sent or received from a peer +/// An [`init`] message to be sent to or received from a peer. +/// +/// [`init`]: https://github.com/lightning/bolts/blob/master/01-messaging.md#the-init-message #[derive(Clone, Debug, PartialEq, Eq)] pub struct Init { - /// The relevant features which the sender supports + /// The relevant features which the sender supports. pub features: InitFeatures, - /// The receipient's network address. This adds the option to report a remote IP address - /// back to a connecting peer using the init message. A node can decide to use that information - /// to discover a potential update to its public IPv4 address (NAT) and use - /// that for a node_announcement update message containing the new address. + /// The receipient's network address. + /// + /// This adds the option to report a remote IP address back to a connecting peer using the init + /// message. A node can decide to use that information to discover a potential update to its + /// public IPv4 address (NAT) and use that for a [`NodeAnnouncement`] update message containing + /// the new address. pub remote_network_address: Option, } -/// An error message to be sent or received from a peer +/// An [`error`] message to be sent to or received from a peer. +/// +/// [`error`]: https://github.com/lightning/bolts/blob/master/01-messaging.md#the-error-and-warning-messages #[derive(Clone, Debug, PartialEq, Eq)] pub struct ErrorMessage { /// The channel ID involved in the error. @@ -92,13 +101,16 @@ pub struct ErrorMessage { /// with the sending peer should be closed. pub channel_id: [u8; 32], /// A possibly human-readable error description. - /// The string should be sanitized before it is used (e.g. emitted to logs or printed to - /// stdout). Otherwise, a well crafted error message may trigger a security vulnerability in + /// + /// The string should be sanitized before it is used (e.g., emitted to logs or printed to + /// `stdout`). Otherwise, a well crafted error message may trigger a security vulnerability in /// the terminal emulator or the logging subsystem. pub data: String, } -/// A warning message to be sent or received from a peer +/// A [`warning`] message to be sent to or received from a peer. +/// +/// [`warning`]: https://github.com/lightning/bolts/blob/master/01-messaging.md#the-error-and-warning-messages #[derive(Clone, Debug, PartialEq, Eq)] pub struct WarningMessage { /// The channel ID involved in the warning. @@ -106,31 +118,40 @@ pub struct WarningMessage { /// All-0s indicates a warning unrelated to a specific channel. pub channel_id: [u8; 32], /// A possibly human-readable warning description. + /// /// The string should be sanitized before it is used (e.g. emitted to logs or printed to /// stdout). Otherwise, a well crafted error message may trigger a security vulnerability in /// the terminal emulator or the logging subsystem. pub data: String, } -/// A ping message to be sent or received from a peer +/// A [`ping`] message to be sent to or received from a peer. +/// +/// [`ping`]: https://github.com/lightning/bolts/blob/master/01-messaging.md#the-ping-and-pong-messages #[derive(Clone, Debug, PartialEq, Eq)] pub struct Ping { - /// The desired response length + /// The desired response length. pub ponglen: u16, /// The ping packet size. + /// /// This field is not sent on the wire. byteslen zeros are sent. pub byteslen: u16, } -/// A pong message to be sent or received from a peer +/// A [`pong`] message to be sent to or received from a peer. +/// +/// [`pong`]: https://github.com/lightning/bolts/blob/master/01-messaging.md#the-ping-and-pong-messages #[derive(Clone, Debug, PartialEq, Eq)] pub struct Pong { /// The pong packet size. + /// /// This field is not sent on the wire. byteslen zeros are sent. pub byteslen: u16, } -/// An open_channel message to be sent or received from a peer +/// An [`open_channel`] message to be sent to or received from a peer. +/// +/// [`open_channel`]: https://github.com/lightning/bolts/blob/master/02-peer-protocol.md#the-open_channel-message #[derive(Clone, Debug, PartialEq, Eq)] pub struct OpenChannel { /// The genesis hash of the blockchain where the channel is to be opened @@ -149,9 +170,11 @@ pub struct OpenChannel { pub channel_reserve_satoshis: u64, /// The minimum HTLC size incoming to sender, in milli-satoshi pub htlc_minimum_msat: u64, - /// The feerate per 1000-weight of sender generated transactions, until updated by update_fee + /// The feerate per 1000-weight of sender generated transactions, until updated by + /// [`UpdateFee`] pub feerate_per_kw: u32, - /// The number of blocks which the counterparty will have to wait to claim on-chain funds if they broadcast a commitment transaction + /// The number of blocks which the counterparty will have to wait to claim on-chain funds if + /// they broadcast a commitment transaction pub to_self_delay: u16, /// The maximum number of inbound HTLCs towards sender pub max_accepted_htlcs: u16, @@ -167,17 +190,20 @@ pub struct OpenChannel { pub htlc_basepoint: PublicKey, /// The first to-be-broadcast-by-sender transaction's per commitment point pub first_per_commitment_point: PublicKey, - /// Channel flags + /// The channel flags to be used pub channel_flags: u8, - /// Optionally, a request to pre-set the to-sender output's scriptPubkey for when we collaboratively close + /// Optionally, a request to pre-set the to-sender output's `scriptPubkey` for when we collaboratively close pub shutdown_scriptpubkey: OptionalField