Merge pull request #848 from TheBlueMatt/2021-03-doc-cleanups

Clean up doc links and enforce them in CI

Author: TheBlueMatt

background-processor/src/lib.rs

@@ -1,3 +1,11 @@
+//! Utilities that take care of tasks that (1) need to happen periodically to keep Rust-Lightning
+//! running properly, and (2) either can or should be run in the background. See docs for
+//! [`BackgroundProcessor`] for more details on the nitty-gritty.
+
+#![deny(broken_intra_doc_links)]
+#![deny(missing_docs)]
+#![deny(unsafe_code)]
+
 #[macro_use] extern crate lightning;
 
 use lightning::chain;
@@ -40,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<PM, Signer, M, T, K, F, L>(persist_manager: PM, manager: Arc<ChannelManager<Signer, Arc<M>, Arc<T>, Arc<K>, Arc<F>, Arc<L>>>, logger: Arc<L>) -> Self
 	where Signer: 'static + Sign,
 	      M: 'static + chain::Watch<Signer>,

ci/check-compiles.sh

@@ -3,4 +3,6 @@ set -e
 set -x
 echo Testing $(git log -1 --oneline)
 cargo check
+cargo doc
+cargo doc --document-private-items
 cd fuzz && cargo check --features=stdin_fuzz

lightning-block-sync/src/http.rs

@@ -1,3 +1,6 @@
+//! Simple HTTP implementation which supports both async and traditional execution environments
+//! with minimal dependencies. This is used as the basis for REST and RPC clients.
+
 use chunked_transfer;
 use serde_json;
 

lightning-block-sync/src/init.rs

@@ -1,3 +1,6 @@
+//! Utilities to assist in the initial sync required to initialize or reload Rust-Lightning objects
+//! from disk.
+
 use crate::{BlockSource, BlockSourceResult, Cache, ChainNotifier};
 use crate::poll::{ChainPoller, Validate, ValidatedBlockHeader};
 
@@ -11,6 +14,8 @@ use lightning::chain;
 ///
 /// Upon success, the returned header can be used to initialize [`SpvClient`]. Useful during a fresh
 /// start when there are no chain listeners to sync yet.
+///
+/// [`SpvClient`]: crate::SpvClient
 pub async fn validate_best_block_header<B: BlockSource>(block_source: &mut B) ->
 BlockSourceResult<ValidatedBlockHeader> {
 	let (best_block_hash, best_block_height) = block_source.get_best_block().await?;
@@ -113,9 +118,9 @@ BlockSourceResult<ValidatedBlockHeader> {
 /// }
 /// ```
 ///
-/// [`SpvClient`]: ../struct.SpvClient.html
-/// [`ChannelManager`]: ../../lightning/ln/channelmanager/struct.ChannelManager.html
-/// [`ChannelMonitor`]: ../../lightning/chain/channelmonitor/struct.ChannelMonitor.html
+/// [`SpvClient`]: crate::SpvClient
+/// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
+/// [`ChannelMonitor`]: lightning::chain::channelmonitor::ChannelMonitor
 pub async fn synchronize_listeners<B: BlockSource, C: Cache>(
 	block_source: &mut B,
 	network: Network,

lightning-block-sync/src/lib.rs

@@ -12,9 +12,10 @@
 //!
 //! 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)]
+#![deny(unsafe_code)]
 
 #[cfg(any(feature = "rest-client", feature = "rpc-client"))]
 pub mod http;
@@ -69,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<u32>)>;
 }
 
@@ -176,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>;
@@ -218,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,
@@ -273,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,

lightning-block-sync/src/poll.rs

@@ -1,3 +1,5 @@
+//! Adapters that make one or more [`BlockSource`]s simpler to poll for new chain tip transitions.
+
 use crate::{AsyncBlockSourceResult, BlockHeaderData, BlockSource, BlockSourceError, BlockSourceResult};
 
 use bitcoin::blockdata::block::Block;

lightning-block-sync/src/rest.rs

@@ -1,3 +1,6 @@
+//! Simple REST client implementation which implements [`BlockSource`] against a Bitcoin Core REST
+//! endpoint.
+
 use crate::{BlockHeaderData, BlockSource, AsyncBlockSourceResult};
 use crate::http::{BinaryResponse, HttpEndpoint, HttpClient, JsonResponse};
 

lightning-block-sync/src/rpc.rs

@@ -1,3 +1,6 @@
+//! Simple RPC client implementation which implements [`BlockSource`] against a Bitcoin Core RPC
+//! endpoint.
+
 use crate::{BlockHeaderData, BlockSource, AsyncBlockSourceResult};
 use crate::http::{HttpClient, HttpEndpoint, JsonResponse};
 

lightning-net-tokio/src/lib.rs

@@ -72,6 +72,9 @@
 //! }
 //! ```
 
+#![deny(broken_intra_doc_links)]
+#![deny(missing_docs)]
+
 use bitcoin::secp256k1::key::PublicKey;
 
 use tokio::net::TcpStream;

lightning-persister/src/lib.rs

@@ -1,3 +1,8 @@
+//! Utilities that handle persisting Rust-Lightning data to disk via standard filesystem APIs.
+
+#![deny(broken_intra_doc_links)]
+#![deny(missing_docs)]
+
 mod util;
 
 extern crate lightning;
@@ -72,6 +77,7 @@ impl FilesystemPersister {
 		}
 	}
 
+	/// Get the directory which was provided when this persister was initialized.
 	pub fn get_data_dir(&self) -> String {
 		self.path_to_channel_data.clone()
 	}