docs: cleanup discv4 docs (paradigmxyz#13884)

Author: mattsse

crates/net/discv4/src/lib.rs

@@ -157,9 +157,10 @@ pub(crate) type IngressReceiver = mpsc::Receiver<IngressEvent>;
 
 type NodeRecordSender = OneshotSender<Vec<NodeRecord>>;
 
-/// The Discv4 frontend
+/// The Discv4 frontend.
 ///
-/// This communicates with the [`Discv4Service`] by sending commands over a channel.
+/// This is a cloneable type that communicates with the [`Discv4Service`] by sending commands over a
+/// shared channel.
 ///
 /// See also [`Discv4::spawn`]
 #[derive(Debug, Clone)]
@@ -174,11 +175,10 @@ pub struct Discv4 {
     node_record: Arc<Mutex<NodeRecord>>,
 }
 
-// === impl Discv4 ===
-
 impl Discv4 {
-    /// Same as [`Self::bind`] but also spawns the service onto a new task,
-    /// [`Discv4Service::spawn()`]
+    /// Same as [`Self::bind`] but also spawns the service onto a new task.
+    ///
+    /// See also: [`Discv4Service::spawn()`]
     pub async fn spawn(
         local_address: SocketAddr,
         local_enr: NodeRecord,
@@ -421,6 +421,15 @@ impl Discv4 {
 ///
 /// This is a [Stream] to handles incoming and outgoing discv4 messages and emits updates via:
 /// [`Discv4Service::update_stream`].
+///
+/// This type maintains the discv Kademlia routing table and is responsible for performing lookups.
+///
+/// ## Lookups
+///
+/// See also [Recursive Lookups](https://github.com/ethereum/devp2p/blob/master/discv4.md#recursive-lookup).
+/// Lookups are either triggered periodically or performaned on demand: [`Discv4::lookup`]
+/// Newly discovered nodes are emitted as [`DiscoveryUpdate::Added`] event to all subscribers:
+/// [`Discv4Service::update_stream`].
 #[must_use = "Stream does nothing unless polled"]
 pub struct Discv4Service {
     /// Local address of the UDP socket.
@@ -694,7 +703,7 @@ impl Discv4Service {
 
     /// Spawns this services onto a new task
     ///
-    /// Note: requires a running runtime
+    /// Note: requires a running tokio runtime
     pub fn spawn(mut self) -> JoinHandle<()> {
         tokio::task::spawn(async move {
             self.bootstrap();

docs/crates/README.md

@@ -3,7 +3,6 @@
 A tour of the various crates that make up reth.
 
 - [`reth-db`](./db.md)
-- [`reth-discv4`](./discv4.md)
 - [`reth-eth-wire`](./eth-wire.md)
 - [`reth-network`](./network.md)
 - [`reth-stages`](./stages.md)