docs(net): add example docs and fix links (#375)

crates/net/network/Cargo.toml

@@ -38,7 +38,7 @@ async-trait = "0.1"
 bytes = "1.2"
 either = "1.8"
 linked_hash_set = "0.1"
-
+rand = "0.8"
 secp256k1 = { version = "0.24", features = [
     "global-context",
     "rand-std",
@@ -51,5 +51,4 @@ reth-interfaces = { path = "../../interfaces", features = ["test-utils"] }
 reth-provider = { path = "../../storage/provider", features = ["test-utils"] }
 reth-tracing = { path = "../../tracing" }
 
-rand = "0.8"
 

crates/net/network/src/config.rs

@@ -1,3 +1,5 @@
+//! Network config support
+
 use crate::{
     import::{BlockImport, ProofOfStakeBlockImport},
     peers::PeersConfig,
@@ -12,6 +14,19 @@ use std::{
     sync::Arc,
 };
 
+/// reexports for convenience
+#[doc(hidden)]
+mod __reexport {
+    pub use reth_discv4::bootnodes::*;
+    pub use secp256k1::SecretKey;
+}
+pub use __reexport::*;
+
+/// Convenience function to create a new random [`SecretKey`]
+pub fn rng_secret_key() -> SecretKey {
+    SecretKey::new(&mut rand::thread_rng())
+}
+
 /// All network related initialization settings.
 pub struct NetworkConfig<C> {
     /// The client type that can interact with the chain.
@@ -28,7 +43,7 @@ pub struct NetworkConfig<C> {
     pub listener_addr: SocketAddr,
     /// How to instantiate peer manager.
     pub peers_config: PeersConfig,
-    /// How to configure the [`SessionManager`]
+    /// How to configure the [SessionManager](crate::session::SessionManager).
     pub sessions_config: SessionsConfig,
     /// A fork identifier as defined by EIP-2124.
     /// Serves as the chain compatibility identifier.

crates/net/network/src/eth_requests.rs

@@ -54,7 +54,7 @@ pub struct EthRequestHandler<C> {
     #[allow(unused)]
     // TODO use to report spammers
     peers: PeersHandle,
-    /// Incoming request from the [`NetworkManager`].
+    /// Incoming request from the [NetworkManager](crate::NetworkManager).
     incoming_requests: UnboundedReceiverStream<IncomingEthRequest>,
 }
 

crates/net/network/src/lib.rs

@@ -1,5 +1,6 @@
 #![warn(missing_docs)]
-#![deny(unused_must_use, rust_2018_idioms)]
+#![deny(unused_must_use, rust_2018_idioms, rustdoc::broken_intra_doc_links)]
+#![allow(rustdoc::private_intra_doc_links)]
 #![doc(test(
     no_crate_inject,
     attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
@@ -12,9 +13,44 @@
 //! In order for a node to join the ethereum p2p network it needs to know what nodes are already
 //! port of that network. This includes public identities (public key) and addresses (where to reach
 //! them).
+//!
+//! ## Usage
+//!
+//! ### Configure and launch the network
+//!
+//! The [`NetworkConfig`] is used to configure the network.
+//! It requires an instance of [`BlockProvider`](reth_provider::BlockProvider).
+//!
+//!
+//! ```
+//! # async fn launch() {
+//! use std::sync::Arc;
+//! use reth_network::config::{rng_secret_key, mainnet_nodes};
+//! use reth_network::{NetworkConfig, NetworkManager};
+//! use reth_provider::test_utils::TestApi;
+//!
+//! // This block provider implementation is used for testing purposes.
+//! let client = Arc::new(TestApi::default());
+//!
+//! // The key that's used for encrypting sessions and to identify our node.
+//! let local_key = rng_secret_key();
+//!
+//! let config = NetworkConfig::builder(client, local_key).boot_nodes(
+//!     mainnet_nodes()
+//! ).build();
+//!
+//! // create the network instance
+//! let network = NetworkManager::new(config).await.unwrap();
+//!
+//! // keep a handle to the network and spawn it
+//! let handle = network.handle().clone();
+//! tokio::task::spawn(network);
+//!
+//! # }
+//! ```
 
 mod cache;
-mod config;
+pub mod config;
 mod discovery;
 pub mod error;
 pub mod eth_requests;

crates/net/network/src/manager.rs

@@ -1,7 +1,7 @@
 //! High level network management.
 //!
-//! The [`Network`] contains the state of the network as a whole. It controls how connections are
-//! handled and keeps track of connections to peers.
+//! The [`NetworkManager`] contains the state of the network as a whole. It controls how connections
+//! are handled and keeps track of connections to peers.
 //!
 //! ## Capabilities
 //!
@@ -86,11 +86,13 @@ pub struct NetworkManager<C> {
     from_handle_rx: UnboundedReceiverStream<NetworkHandleMessage>,
     /// Handles block imports according to the `eth` protocol.
     block_import: Box<dyn BlockImport>,
-    /// All listeners for [`Network`] events.
+    /// All listeners for high level network events.
     event_listeners: NetworkEventListeners,
-    /// Sender half to send events to the [`TransactionsManager`] task, if configured.
+    /// Sender half to send events to the
+    /// [`TransactionsManager`](crate::transactions::TransactionsManager) task, if configured.
     to_transactions_manager: Option<mpsc::UnboundedSender<NetworkTransactionEvent>>,
-    /// Sender half to send events to the [`EthRequestHandler`] task, if configured.
+    /// Sender half to send events to the
+    /// [`EthRequestHandler`](crate::eth_requests::EthRequestHandler) task, if configured.
     to_eth_request_handler: Option<mpsc::UnboundedSender<IncomingEthRequest>>,
     /// Tracks the number of active session (connected peers).
     ///
@@ -167,12 +169,14 @@ where
         })
     }
 
-    /// Sets the dedicated channel for events indented for the [`TransactionsManager`]
+    /// Sets the dedicated channel for events indented for the
+    /// [`TransactionsManager`](crate::transactions::TransactionsManager).
     pub fn set_transactions(&mut self, tx: mpsc::UnboundedSender<NetworkTransactionEvent>) {
         self.to_transactions_manager = Some(tx);
     }
 
-    /// Sets the dedicated channel for events indented for the [`EthRequestHandler`]
+    /// Sets the dedicated channel for events indented for the
+    /// [`EthRequestHandler`](crate::eth_requests::EthRequestHandler).
     pub fn set_eth_request_handler(&mut self, tx: mpsc::UnboundedSender<IncomingEthRequest>) {
         self.to_eth_request_handler = Some(tx);
     }
@@ -232,14 +236,16 @@ where
             .apply_reputation_change(&peer_id, ReputationChangeKind::BadProtocol);
     }
 
-    /// Sends an event to the [`TransactionsManager`] if configured
+    /// Sends an event to the [`TransactionsManager`](crate::transactions::TransactionsManager) if
+    /// configured.
     fn notify_tx_manager(&self, event: NetworkTransactionEvent) {
         if let Some(ref tx) = self.to_transactions_manager {
             let _ = tx.send(event);
         }
     }
 
-    /// Sends an event to the [`EthRequestManager`] if configured
+    /// Sends an event to the [`EthRequestManager`](crate::eth_requests::EthRequestHandler) if
+    /// configured.
     fn delegate_eth_request(&self, event: IncomingEthRequest) {
         if let Some(ref reqs) = self.to_eth_request_handler {
             let _ = reqs.send(event);

crates/net/network/src/network.rs

@@ -109,13 +109,14 @@ impl NetworkHandle {
         self.send_message(NetworkHandleMessage::AnnounceBlock(block, hash))
     }
 
-    /// Sends a message to the [`NetworkManager`] to add a peer to the known set
+    /// Sends a message to the [`NetworkManager`](crate::NetworkManager) to add a peer to the known
+    /// set
     pub fn add_peer(&self, peer: PeerId, addr: SocketAddr) {
         let _ = self.inner.to_manager_tx.send(NetworkHandleMessage::AddPeerAddress(peer, addr));
     }
 
-    /// Sends a message to the [`NetworkManager`] to disconnect an existing connection to the given
-    /// peer.
+    /// Sends a message to the [`NetworkManager`](crate::NetworkManager)  to disconnect an existing
+    /// connection to the given peer.
     pub fn disconnect_peer(&self, peer: PeerId) {
         self.send_message(NetworkHandleMessage::DisconnectPeer(peer))
     }

crates/net/network/src/session/config.rs

@@ -1,4 +1,4 @@
-//! Configuration types for [`SessionsManager`]
+//! Configuration types for [SessionManager](crate::session::SessionManager).
 
 use crate::session::{Direction, ExceedsSessionLimit};
 use std::time::Duration;
@@ -6,7 +6,7 @@ use std::time::Duration;
 /// Default request timeout.
 pub const REQUEST_TIMEOUT: Duration = Duration::from_millis(500u64);
 
-/// Configuration options when creating a [`SessionsManager`].
+/// Configuration options when creating a [SessionManager](crate::session::SessionManager).
 pub struct SessionsConfig {
     /// Size of the session command buffer (per session task).
     pub session_command_buffer: usize,

crates/net/network/src/transactions.rs

@@ -99,7 +99,7 @@ pub struct TransactionsManager<Pool> {
     command_rx: UnboundedReceiverStream<TransactionsCommand>,
     /// Incoming commands from [`TransactionsHandle`].
     pending_transactions: ReceiverStream<TxHash>,
-    /// Incoming events from the [`NetworkManager`]
+    /// Incoming events from the [`NetworkManager`](crate::NetworkManager).
     transaction_events: UnboundedReceiverStream<NetworkTransactionEvent>,
 }
 
@@ -112,7 +112,7 @@ where
 {
     /// Sets up a new instance.
     ///
-    /// Note: This expects an existing [`NetworkManager`] instance.
+    /// Note: This expects an existing [`NetworkManager`](crate::NetworkManager) instance.
     pub fn new(
         network: NetworkHandle,
         pool: Pool,