From: Matt Corallo Date: Wed, 17 Mar 2021 19:53:29 +0000 (-0400) Subject: Drop all HTML-relative links since rustdoc now supports resolution X-Git-Tag: v0.0.14~46^2~1 X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=commitdiff_plain;h=836985a5e5e8036d5dea47797ef6fba498616e67;p=rust-lightning Drop all HTML-relative links since rustdoc now supports resolution --- diff --git a/background-processor/src/lib.rs b/background-processor/src/lib.rs index 286bfedd..c3db4d55 100644 --- a/background-processor/src/lib.rs +++ b/background-processor/src/lib.rs @@ -48,18 +48,21 @@ impl BackgroundProcessor { /// Start a background thread that takes care of responsibilities enumerated in the top-level /// documentation. /// - /// If `persist_manager` returns an error, then this thread will return said error (and `start()` - /// will need to be called again to restart the `BackgroundProcessor`). Users should wait on - /// [`thread_handle`]'s `join()` method to be able to tell if and when an error is returned, or - /// implement `persist_manager` such that an error is never returned to the `BackgroundProcessor` + /// If `persist_manager` returns an error, then this thread will return said error (and + /// `start()` will need to be called again to restart the `BackgroundProcessor`). Users should + /// wait on [`thread_handle`]'s `join()` method to be able to tell if and when an error is + /// returned, or implement `persist_manager` such that an error is never returned to the + /// `BackgroundProcessor` /// - /// `persist_manager` is responsible for writing out the `ChannelManager` to disk, and/or uploading - /// to one or more backup services. See [`ChannelManager::write`] for writing out a `ChannelManager`. - /// See [`FilesystemPersister::persist_manager`] for Rust-Lightning's provided implementation. + /// `persist_manager` is responsible for writing out the [`ChannelManager`] to disk, and/or + /// uploading to one or more backup services. See [`ChannelManager::write`] for writing out a + /// [`ChannelManager`]. See [`FilesystemPersister::persist_manager`] for Rust-Lightning's + /// provided implementation. /// - /// [`thread_handle`]: struct.BackgroundProcessor.html#structfield.thread_handle - /// [`ChannelManager::write`]: ../lightning/ln/channelmanager/struct.ChannelManager.html#method.write - /// [`FilesystemPersister::persist_manager`]: ../lightning_persister/struct.FilesystemPersister.html#impl + /// [`thread_handle`]: BackgroundProcessor::thread_handle + /// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager + /// [`ChannelManager::write`]: lightning::ln::channelmanager::ChannelManager#impl-Writeable + /// [`FilesystemPersister::persist_manager`]: lightning_persister::FilesystemPersister::persist_manager pub fn start(persist_manager: PM, manager: Arc, Arc, Arc, Arc, Arc>>, logger: Arc) -> Self where Signer: 'static + Sign, M: 'static + chain::Watch, diff --git a/lightning-block-sync/src/lib.rs b/lightning-block-sync/src/lib.rs index 6f227b10..bc937b59 100644 --- a/lightning-block-sync/src/lib.rs +++ b/lightning-block-sync/src/lib.rs @@ -12,9 +12,6 @@ //! //! Both features support either blocking I/O using `std::net::TcpStream` or, with feature `tokio`, //! non-blocking I/O using `tokio::net::TcpStream` from inside a Tokio runtime. -//! -//! [`SpvClient`]: struct.SpvClient.html -//! [`BlockSource`]: trait.BlockSource.html #![deny(broken_intra_doc_links)] #![deny(missing_docs)] @@ -73,8 +70,7 @@ pub trait BlockSource : Sync + Send { /// When polling a block source, [`Poll`] implementations may pass the height to [`get_header`] /// to allow for a more efficient lookup. /// - /// [`Poll`]: poll/trait.Poll.html - /// [`get_header`]: #tymethod.get_header + /// [`get_header`]: Self::get_header fn get_best_block<'a>(&'a mut self) -> AsyncBlockSourceResult<(BlockHash, Option)>; } @@ -180,8 +176,6 @@ where L::Target: chain::Listen { /// Implementations may define how long to retain headers such that it's unlikely they will ever be /// needed to disconnect a block. In cases where block sources provide access to headers on stale /// forks reliably, caches may be entirely unnecessary. -/// -/// [`ChainNotifier`]: struct.ChainNotifier.html pub trait Cache { /// Retrieves the block header keyed by the given block hash. fn look_up(&self, block_hash: &BlockHash) -> Option<&ValidatedBlockHeader>; @@ -222,7 +216,7 @@ impl<'a, P: Poll, C: Cache, L: Deref> SpvClient<'a, P, C, L> where L::Target: ch /// * `header_cache` is used to look up and store headers on the best chain /// * `chain_listener` is notified of any blocks connected or disconnected /// - /// [`poll_best_tip`]: struct.SpvClient.html#method.poll_best_tip + /// [`poll_best_tip`]: SpvClient::poll_best_tip pub fn new( chain_tip: ValidatedBlockHeader, chain_poller: P, @@ -277,7 +271,7 @@ impl<'a, P: Poll, C: Cache, L: Deref> SpvClient<'a, P, C, L> where L::Target: ch /// Notifies [listeners] of blocks that have been connected or disconnected from the chain. /// -/// [listeners]: ../../lightning/chain/trait.Listen.html +/// [listeners]: lightning::chain::Listen pub struct ChainNotifier<'a, C: Cache, L: Deref> where L::Target: chain::Listen { /// Cache for looking up headers before fetching from a block source. header_cache: &'a mut C, diff --git a/lightning/src/chain/chainmonitor.rs b/lightning/src/chain/chainmonitor.rs index 0cf2d56a..eb17b469 100644 --- a/lightning/src/chain/chainmonitor.rs +++ b/lightning/src/chain/chainmonitor.rs @@ -13,21 +13,15 @@ //! update [`ChannelMonitor`]s accordingly. If any on-chain events need further processing, it will //! make those available as [`MonitorEvent`]s to be consumed. //! -//! `ChainMonitor` is parameterized by an optional chain source, which must implement the +//! [`ChainMonitor`] is parameterized by an optional chain source, which must implement the //! [`chain::Filter`] trait. This provides a mechanism to signal new relevant outputs back to light //! clients, such that transactions spending those outputs are included in block data. //! -//! `ChainMonitor` may be used directly to monitor channels locally or as a part of a distributed -//! setup to monitor channels remotely. In the latter case, a custom `chain::Watch` implementation +//! [`ChainMonitor`] may be used directly to monitor channels locally or as a part of a distributed +//! setup to monitor channels remotely. In the latter case, a custom [`chain::Watch`] implementation //! would be responsible for routing each update to a remote server and for retrieving monitor -//! events. The remote server would make use of `ChainMonitor` for block processing and for -//! servicing `ChannelMonitor` updates from the client. -//! -//! [`ChainMonitor`]: struct.ChainMonitor.html -//! [`chain::Filter`]: ../trait.Filter.html -//! [`chain::Watch`]: ../trait.Watch.html -//! [`ChannelMonitor`]: ../channelmonitor/struct.ChannelMonitor.html -//! [`MonitorEvent`]: ../channelmonitor/enum.MonitorEvent.html +//! events. The remote server would make use of [`ChainMonitor`] for block processing and for +//! servicing [`ChannelMonitor`] updates from the client. use bitcoin::blockdata::block::{Block, BlockHeader}; @@ -53,9 +47,8 @@ use std::ops::Deref; /// or used independently to monitor channels remotely. See the [module-level documentation] for /// details. /// -/// [`chain::Watch`]: ../trait.Watch.html -/// [`ChannelManager`]: ../../ln/channelmanager/struct.ChannelManager.html -/// [module-level documentation]: index.html +/// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager +/// [module-level documentation]: crate::chain::chainmonitor pub struct ChainMonitor where C::Target: chain::Filter, T::Target: BroadcasterInterface, @@ -88,10 +81,6 @@ where C::Target: chain::Filter, /// calls must not exclude any transactions matching the new outputs nor any in-block /// descendants of such transactions. It is not necessary to re-fetch the block to obtain /// updated `txdata`. - /// - /// [`ChannelMonitor::block_connected`]: ../channelmonitor/struct.ChannelMonitor.html#method.block_connected - /// [`chain::Watch::release_pending_monitor_events`]: ../trait.Watch.html#tymethod.release_pending_monitor_events - /// [`chain::Filter`]: ../trait.Filter.html pub fn block_connected(&self, header: &BlockHeader, txdata: &TransactionData, height: u32) { let monitors = self.monitors.read().unwrap(); for monitor in monitors.values() { @@ -110,8 +99,6 @@ where C::Target: chain::Filter, /// Dispatches to per-channel monitors, which are responsible for updating their on-chain view /// of a channel based on the disconnected block. See [`ChannelMonitor::block_disconnected`] for /// details. - /// - /// [`ChannelMonitor::block_disconnected`]: ../channelmonitor/struct.ChannelMonitor.html#method.block_disconnected pub fn block_disconnected(&self, header: &BlockHeader, disconnected_height: u32) { let monitors = self.monitors.read().unwrap(); for monitor in monitors.values() { @@ -126,8 +113,6 @@ where C::Target: chain::Filter, /// pre-filter blocks or only fetch blocks matching a compact filter. Otherwise, clients may /// always need to fetch full blocks absent another means for determining which blocks contain /// transactions relevant to the watched channels. - /// - /// [`chain::Filter`]: ../trait.Filter.html pub fn new(chain_source: Option, broadcaster: T, logger: L, feeest: F, persister: P) -> Self { Self { monitors: RwLock::new(HashMap::new()), @@ -174,8 +159,6 @@ where C::Target: chain::Filter, /// /// Note that we persist the given `ChannelMonitor` while holding the `ChainMonitor` /// monitors lock. - /// - /// [`chain::Filter`]: ../trait.Filter.html fn watch_channel(&self, funding_outpoint: OutPoint, monitor: ChannelMonitor) -> Result<(), ChannelMonitorUpdateErr> { let mut monitors = self.monitors.write().unwrap(); let entry = match monitors.entry(funding_outpoint) { diff --git a/lightning/src/chain/channelmonitor.rs b/lightning/src/chain/channelmonitor.rs index c2c791c4..24dfc57b 100644 --- a/lightning/src/chain/channelmonitor.rs +++ b/lightning/src/chain/channelmonitor.rs @@ -19,8 +19,6 @@ //! ChannelMonitors should do so). Thus, if you're building rust-lightning into an HSM or other //! security-domain-separated system design, you should consider having multiple paths for //! ChannelMonitors to get out of the HSM and onto monitoring devices. -//! -//! [`chain::Watch`]: ../trait.Watch.html use bitcoin::blockdata::block::{Block, BlockHeader}; use bitcoin::blockdata::transaction::{TxOut,Transaction}; @@ -75,8 +73,6 @@ pub struct ChannelMonitorUpdate { /// The only instance where update_id values are not strictly increasing is the case where we /// allow post-force-close updates with a special update ID of [`CLOSED_CHANNEL_UPDATE_ID`]. See /// its docs for more details. - /// - /// [`CLOSED_CHANNEL_UPDATE_ID`]: constant.CLOSED_CHANNEL_UPDATE_ID.html pub update_id: u64, } @@ -193,8 +189,6 @@ pub enum MonitorEvent { /// Simple structure sent back by `chain::Watch` when an HTLC from a forward channel is detected on /// chain. Used to update the corresponding HTLC in the backward channel. Failing to pass the /// preimage claim backward will lead to loss of funds. -/// -/// [`chain::Watch`]: ../trait.Watch.html #[derive(Clone, PartialEq)] pub struct HTLCUpdate { pub(crate) payment_hash: PaymentHash, @@ -1187,8 +1181,6 @@ impl ChannelMonitor { /// Get the list of HTLCs who's status has been updated on chain. This should be called by /// ChannelManager via [`chain::Watch::release_pending_monitor_events`]. - /// - /// [`chain::Watch::release_pending_monitor_events`]: ../trait.Watch.html#tymethod.release_pending_monitor_events pub fn get_and_clear_pending_monitor_events(&self) -> Vec { self.inner.lock().unwrap().get_and_clear_pending_monitor_events() } @@ -2450,11 +2442,8 @@ pub trait Persist: Send + Sync { /// stored channel data). Note that you **must** persist every new monitor to /// disk. See the `Persist` trait documentation for more details. /// - /// See [`ChannelMonitor::serialize_for_disk`] for writing out a `ChannelMonitor`, + /// See [`ChannelMonitor::write`] for writing out a `ChannelMonitor`, /// and [`ChannelMonitorUpdateErr`] for requirements when returning errors. - /// - /// [`ChannelMonitor::serialize_for_disk`]: struct.ChannelMonitor.html#method.serialize_for_disk - /// [`ChannelMonitorUpdateErr`]: enum.ChannelMonitorUpdateErr.html fn persist_new_channel(&self, id: OutPoint, data: &ChannelMonitor) -> Result<(), ChannelMonitorUpdateErr>; /// Update one channel's data. The provided `ChannelMonitor` has already @@ -2476,14 +2465,9 @@ pub trait Persist: Send + Sync { /// them in batches. The size of each monitor grows `O(number of state updates)` /// whereas updates are small and `O(1)`. /// - /// See [`ChannelMonitor::serialize_for_disk`] for writing out a `ChannelMonitor`, + /// See [`ChannelMonitor::write`] for writing out a `ChannelMonitor`, /// [`ChannelMonitorUpdate::write`] for writing out an update, and /// [`ChannelMonitorUpdateErr`] for requirements when returning errors. - /// - /// [`ChannelMonitor::update_monitor`]: struct.ChannelMonitor.html#impl-1 - /// [`ChannelMonitor::serialize_for_disk`]: struct.ChannelMonitor.html#method.serialize_for_disk - /// [`ChannelMonitorUpdate::write`]: struct.ChannelMonitorUpdate.html#method.write - /// [`ChannelMonitorUpdateErr`]: enum.ChannelMonitorUpdateErr.html fn update_persisted_channel(&self, id: OutPoint, update: &ChannelMonitorUpdate, data: &ChannelMonitor) -> Result<(), ChannelMonitorUpdateErr>; } diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs index c1fceec8..7d410b9b 100644 --- a/lightning/src/chain/mod.rs +++ b/lightning/src/chain/mod.rs @@ -25,8 +25,6 @@ pub mod transaction; pub mod keysinterface; /// An error when accessing the chain via [`Access`]. -/// -/// [`Access`]: trait.Access.html #[derive(Clone)] pub enum AccessError { /// The requested chain is unknown. @@ -77,9 +75,9 @@ pub trait Listen { /// funds in the channel. See [`ChannelMonitorUpdateErr`] for more details about how to handle /// multiple instances. /// -/// [`ChannelMonitor`]: channelmonitor/struct.ChannelMonitor.html -/// [`ChannelMonitorUpdateErr`]: channelmonitor/enum.ChannelMonitorUpdateErr.html -/// [`PermanentFailure`]: channelmonitor/enum.ChannelMonitorUpdateErr.html#variant.PermanentFailure +/// [`ChannelMonitor`]: channelmonitor::ChannelMonitor +/// [`ChannelMonitorUpdateErr`]: channelmonitor::ChannelMonitorUpdateErr +/// [`PermanentFailure`]: channelmonitor::ChannelMonitorUpdateErr::PermanentFailure pub trait Watch: Send + Sync { /// Watches a channel identified by `funding_txo` using `monitor`. /// @@ -87,9 +85,9 @@ pub trait Watch: Send + Sync { /// with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means /// calling [`block_connected`] and [`block_disconnected`] on the monitor. /// - /// [`get_outputs_to_watch`]: channelmonitor/struct.ChannelMonitor.html#method.get_outputs_to_watch - /// [`block_connected`]: channelmonitor/struct.ChannelMonitor.html#method.block_connected - /// [`block_disconnected`]: channelmonitor/struct.ChannelMonitor.html#method.block_disconnected + /// [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch + /// [`block_connected`]: channelmonitor::ChannelMonitor::block_connected + /// [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected fn watch_channel(&self, funding_txo: OutPoint, monitor: ChannelMonitor) -> Result<(), ChannelMonitorUpdateErr>; /// Updates a channel identified by `funding_txo` by applying `update` to its monitor. @@ -97,8 +95,8 @@ pub trait Watch: Send + Sync { /// Implementations must call [`update_monitor`] with the given update. See /// [`ChannelMonitorUpdateErr`] for invariants around returning an error. /// - /// [`update_monitor`]: channelmonitor/struct.ChannelMonitor.html#method.update_monitor - /// [`ChannelMonitorUpdateErr`]: channelmonitor/enum.ChannelMonitorUpdateErr.html + /// [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor + /// [`ChannelMonitorUpdateErr`]: channelmonitor::ChannelMonitorUpdateErr fn update_channel(&self, funding_txo: OutPoint, update: ChannelMonitorUpdate) -> Result<(), ChannelMonitorUpdateErr>; /// Returns any monitor events since the last call. Subsequent calls must only return new @@ -120,11 +118,10 @@ pub trait Watch: Send + Sync { /// /// Note that use as part of a [`Watch`] implementation involves reentrancy. Therefore, the `Filter` /// should not block on I/O. Implementations should instead queue the newly monitored data to be -/// processed later. Then, in order to block until the data has been processed, any `Watch` +/// processed later. Then, in order to block until the data has been processed, any [`Watch`] /// invocation that has called the `Filter` must return [`TemporaryFailure`]. /// -/// [`Watch`]: trait.Watch.html -/// [`TemporaryFailure`]: channelmonitor/enum.ChannelMonitorUpdateErr.html#variant.TemporaryFailure +/// [`TemporaryFailure`]: channelmonitor::ChannelMonitorUpdateErr::TemporaryFailure /// [BIP 157]: https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki /// [BIP 158]: https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki pub trait Filter: Send + Sync { diff --git a/lightning/src/ln/features.rs b/lightning/src/ln/features.rs index 549663c9..259bda85 100644 --- a/lightning/src/ln/features.rs +++ b/lightning/src/ln/features.rs @@ -12,8 +12,7 @@ //! Lightning nodes advertise a supported set of operation through feature flags. Features are //! applicable for a specific context as indicated in some [messages]. [`Features`] encapsulates //! behavior for specifying and checking feature flags for a particular context. Each feature is -//! defined internally by a trait specifying the corresponding flags (i.e., even and odd bits). A -//! [`Context`] is used to parameterize [`Features`] and defines which features it can support. +//! defined internally by a trait specifying the corresponding flags (i.e., even and odd bits). //! //! Whether a feature is considered "known" or "unknown" is relative to the implementation, whereas //! the term "supports" is used in reference to a particular set of [`Features`]. That is, a node @@ -21,9 +20,7 @@ //! And the implementation can interpret a feature if the feature is known to it. //! //! [BOLT #9]: https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md -//! [messages]: ../msgs/index.html -//! [`Features`]: struct.Features.html -//! [`Context`]: sealed/trait.Context.html +//! [messages]: crate::ln::msgs use std::{cmp, fmt}; use std::marker::PhantomData; @@ -36,8 +33,6 @@ mod sealed { /// The context in which [`Features`] are applicable. Defines which features are required and /// which are optional for the context. - /// - /// [`Features`]: ../struct.Features.html pub trait Context { /// Features that are known to the implementation, where a required feature is indicated by /// its even bit and an optional feature is indicated by its odd bit. @@ -51,8 +46,6 @@ mod sealed { /// Defines a [`Context`] by stating which features it requires and which are optional. Features /// are specified as a comma-separated list of bytes where each byte is a pipe-delimited list of /// feature identifiers. - /// - /// [`Context`]: trait.Context.html macro_rules! define_context { ($context: ident { required_features: [$( $( $required_feature: ident )|*, )*], @@ -156,8 +149,6 @@ mod sealed { /// Defines a feature with the given bits for the specified [`Context`]s. The generated trait is /// useful for manipulating feature flags. - /// - /// [`Context`]: trait.Context.html macro_rules! define_feature { ($odd_bit: expr, $feature: ident, [$($context: ty),+], $doc: expr, $optional_setter: ident, $required_setter: ident) => { @@ -413,9 +404,7 @@ impl Features { } } - /// Creates features known by the implementation as defined by [`T::KNOWN_FEATURE_FLAGS`]. - /// - /// [`T::KNOWN_FEATURE_FLAGS`]: sealed/trait.Context.html#associatedconstant.KNOWN_FEATURE_FLAGS + /// Creates a Features with the bits set which are known by the implementation pub fn known() -> Self { Self { flags: T::KNOWN_FEATURE_FLAGS.to_vec(), diff --git a/lightning/src/ln/wire.rs b/lightning/src/ln/wire.rs index 8197ce15..12e77d07 100644 --- a/lightning/src/ln/wire.rs +++ b/lightning/src/ln/wire.rs @@ -9,27 +9,20 @@ //! Wire encoding/decoding for Lightning messages according to [BOLT #1]. //! -//! Messages known by this module can be read from the wire using [`read`]. -//! The [`Message`] enum returned by [`read`] wraps the decoded message or the message type (if +//! Messages known by this module can be read from the wire using [`read()`]. +//! The [`Message`] enum returned by [`read()`] wraps the decoded message or the message type (if //! unknown) to use with pattern matching. //! //! Messages implementing the [`Encode`] trait define a message type and can be sent over the wire -//! using [`write`]. +//! using [`write()`]. //! //! [BOLT #1]: https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md -//! [`read`]: fn.read.html -//! [`write`]: fn.write.html -//! [`Encode`]: trait.Encode.html -//! [`Message`]: enum.Message.html use ln::msgs; use util::ser::{Readable, Writeable, Writer}; -/// A Lightning message returned by [`read`] when decoding bytes received over the wire. Each -/// variant contains a message from [`ln::msgs`] or otherwise the message type if unknown. -/// -/// [`read`]: fn.read.html -/// [`ln::msgs`]: ../msgs/index.html +/// A Lightning message returned by [`read()`] when decoding bytes received over the wire. Each +/// variant contains a message from [`msgs`] or otherwise the message type if unknown. #[allow(missing_docs)] pub enum Message { Init(msgs::Init), @@ -230,16 +223,13 @@ pub fn write(message: &M, buffer: &mut W) -> R /// Defines a type-identified encoding for sending messages over the wire. /// -/// Messages implementing this trait specify a type and must be [`Writeable`] to use with [`write`]. -/// -/// [`Writeable`]: ../../util/ser/trait.Writeable.html -/// [`write`]: fn.write.html +/// Messages implementing this trait specify a type and must be [`Writeable`] to use with [`write()`]. pub trait Encode { /// The type identifying the message payload. const TYPE: u16; /// Returns the type identifying the message payload. Convenience method for accessing - /// [`TYPE`](TYPE). + /// [`Self::TYPE`]. fn type_id(&self) -> MessageType { MessageType(Self::TYPE) }