add missing documentation and minor refactor (paradigmxyz#6152)

crates/consensus/auto-seal/tests/it/auto_mine.rs

@@ -1,4 +1,3 @@
-#![allow(unreachable_pub)]
 //! auto-mine consensus integration test
 
 use clap::Parser;
@@ -58,7 +57,7 @@ impl RethNodeCommandConfig for AutoMineConfig {
 /// process transactions.
 #[test]
 #[cfg_attr(feature = "optimism", ignore)]
-pub fn test_auto_mine() {
+pub(crate) fn test_auto_mine() {
     // create temp path for test
     let temp_path = tempfile::TempDir::new().expect("tempdir is okay").into_path();
     let datadir = temp_path.to_str().expect("temp path is okay");

crates/consensus/beacon/src/engine/message.rs

@@ -141,7 +141,6 @@ impl Future for PendingPayloadId {
 /// A message for the beacon engine from other components of the node (engine RPC API invoked by the
 /// consensus layer).
 #[derive(Debug)]
-#[allow(clippy::large_enum_variant)]
 pub enum BeaconEngineMessage<Engine: EngineTypes> {
     /// Message with new payload.
     NewPayload {

crates/net/discv4/src/proto.rs

@@ -1,7 +1,5 @@
 //! Discovery v4 protocol implementation.
 
-#![allow(missing_docs)]
-
 use crate::{error::DecodePacketError, EnrForkIdEntry, PeerId, MAX_PACKET_SIZE, MIN_PACKET_SIZE};
 use alloy_rlp::{
     length_of_length, Decodable, Encodable, Error as RlpError, Header, RlpDecodable, RlpEncodable,
@@ -19,15 +17,23 @@ use std::net::IpAddr;
 
 // Note: this is adapted from https://github.com/vorot93/discv4
 
-/// Id for message variants.
+/// Represents the identifier for message variants.
+///
+/// This enumeration assigns unique identifiers (u8 values) to different message types.
 #[derive(Debug)]
 #[repr(u8)]
 pub enum MessageId {
+    /// Ping message identifier.
     Ping = 1,
+    /// Pong message identifier.
     Pong = 2,
+    /// Find node message identifier.
     FindNode = 3,
+    /// Neighbours message identifier.
     Neighbours = 4,
+    /// ENR request message identifier.
     EnrRequest = 5,
+    /// ENR response message identifier.
     EnrResponse = 6,
 }
 
@@ -173,11 +179,16 @@ impl Message {
     }
 }
 
-/// Decoded packet
+/// Represents a decoded packet.
+///
+/// This struct holds information about a decoded packet, including the message, node ID, and hash.
 #[derive(Debug)]
 pub struct Packet {
+    /// The decoded message from the packet.
     pub msg: Message,
+    /// The ID of the peer that sent the packet.
     pub node_id: PeerId,
+    /// The hash of the packet.
     pub hash: B256,
 }
 
@@ -231,6 +242,7 @@ pub struct Neighbours {
 pub struct EnrWrapper<K: EnrKey>(Enr<K>);
 
 impl<K: EnrKey> EnrWrapper<K> {
+    /// Creates a new instance of [`EnrWrapper`].
     pub fn new(enr: Enr<K>) -> Self {
         EnrWrapper(enr)
     }
@@ -302,15 +314,24 @@ impl<K: EnrKey> Decodable for EnrWrapper<K> {
 }
 
 /// A [ENRRequest packet](https://github.com/ethereum/devp2p/blob/master/discv4.md#enrrequest-packet-0x05).
+///
+/// This packet is used to request the current version of a node's Ethereum Node Record (ENR).
 #[derive(Clone, Copy, Debug, Eq, PartialEq, RlpEncodable, RlpDecodable)]
 pub struct EnrRequest {
+    /// The expiration timestamp for the request. No reply should be sent if it refers to a time in
+    /// the past.
     pub expire: u64,
 }
 
 /// A [ENRResponse packet](https://github.com/ethereum/devp2p/blob/master/discv4.md#enrresponse-packet-0x06).
+///
+/// This packet is used to respond to an ENRRequest packet and includes the requested ENR along with
+/// the hash of the original request.
 #[derive(Clone, Debug, Eq, PartialEq, RlpEncodable)]
 pub struct EnrResponse {
+    /// The hash of the ENRRequest packet being replied to.
     pub request_hash: B256,
+    /// The ENR (Ethereum Node Record) for the responding node.
     pub enr: EnrWrapper<SecretKey>,
 }
 
@@ -352,11 +373,16 @@ impl Decodable for EnrResponse {
     }
 }
 
+/// Represents a Ping packet.
+///
 /// A [Ping packet](https://github.com/ethereum/devp2p/blob/master/discv4.md#ping-packet-0x01).
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct Ping {
+    /// The sender's endpoint.
     pub from: NodeEndpoint,
+    /// The recipient's endpoint.
     pub to: NodeEndpoint,
+    /// The expiration timestamp.
     pub expire: u64,
     /// Optional enr_seq for <https://eips.ethereum.org/EIPS/eip-868>
     pub enr_sq: Option<u64>,
@@ -440,11 +466,16 @@ impl Decodable for Ping {
     }
 }
 
+/// Represents a Pong packet.
+///
 /// A [Pong packet](https://github.com/ethereum/devp2p/blob/master/discv4.md#pong-packet-0x02).
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Pong {
+    /// The recipient's endpoint.
     pub to: NodeEndpoint,
+    /// The hash of the corresponding ping packet.
     pub echo: B256,
+    /// The expiration timestamp.
     pub expire: u64,
     /// Optional enr_seq for <https://eips.ethereum.org/EIPS/eip-868>
     pub enr_sq: Option<u64>,

crates/net/discv4/src/test_utils.rs

@@ -1,7 +1,5 @@
 //! Mock discovery support
 
-#![allow(missing_docs)]
-
 use crate::{
     proto::{FindNode, Message, Neighbours, NodeEndpoint, Packet, Ping, Pong},
     receive_loop, send_loop, Discv4, Discv4Config, Discv4Service, EgressSender, IngressEvent,
@@ -104,10 +102,12 @@ impl MockDiscovery {
         self.pending_neighbours.insert(target, nodes);
     }
 
+    /// Returns the local socket address associated with the service.
     pub fn local_addr(&self) -> SocketAddr {
         self.local_addr
     }
 
+    /// Returns the local [`NodeRecord`] associated with the service.
     pub fn local_enr(&self) -> NodeRecord {
         self.local_enr
     }
@@ -190,18 +190,44 @@ impl Stream for MockDiscovery {
     }
 }
 
-/// The event type the mock service produces
+/// Represents the event types produced by the mock service.
 #[derive(Debug)]
 pub enum MockEvent {
-    Pong { ping: Ping, pong: Pong, to: SocketAddr },
-    Neighbours { nodes: Vec<NodeRecord>, to: SocketAddr },
+    /// A Pong event, consisting of the original Ping packet, the corresponding Pong packet,
+    /// and the recipient's socket address.
+    Pong {
+        /// The original Ping packet.
+        ping: Ping,
+        /// The corresponding Pong packet.
+        pong: Pong,
+        /// The recipient's socket address.
+        to: SocketAddr,
+    },
+    /// A Neighbours event, containing a list of node records and the recipient's socket address.
+    Neighbours {
+        /// The list of node records.
+        nodes: Vec<NodeRecord>,
+        /// The recipient's socket address.
+        to: SocketAddr,
+    },
 }
 
-/// Command for interacting with the `MockDiscovery` service
+/// Represents commands for interacting with the `MockDiscovery` service.
 #[derive(Debug)]
 pub enum MockCommand {
-    MockPong { node_id: PeerId },
-    MockNeighbours { target: PeerId, nodes: Vec<NodeRecord> },
+    /// A command to simulate a Pong event, including the node ID of the recipient.
+    MockPong {
+        /// The node ID of the recipient.
+        node_id: PeerId,
+    },
+    /// A command to simulate a Neighbours event, including the target node ID and a list of node
+    /// records.
+    MockNeighbours {
+        /// The target node ID.
+        target: PeerId,
+        /// The list of node records.
+        nodes: Vec<NodeRecord>,
+    },
 }
 
 /// Creates a new testing instance for [`Discv4`] and its service
@@ -221,6 +247,7 @@ pub async fn create_discv4_with_config(config: Discv4Config) -> (Discv4, Discv4S
     Discv4::bind(socket, local_enr, secret_key, config).await.unwrap()
 }
 
+/// Generates a random [`NodeEndpoint`] using the provided random number generator.
 pub fn rng_endpoint(rng: &mut impl Rng) -> NodeEndpoint {
     let address = if rng.gen() {
         let mut ip = [0u8; 4];
@@ -234,25 +261,29 @@ pub fn rng_endpoint(rng: &mut impl Rng) -> NodeEndpoint {
     NodeEndpoint { address, tcp_port: rng.gen(), udp_port: rng.gen() }
 }
 
+/// Generates a random [`NodeRecord`] using the provided random number generator.
 pub fn rng_record(rng: &mut impl RngCore) -> NodeRecord {
     let NodeEndpoint { address, udp_port, tcp_port } = rng_endpoint(rng);
     NodeRecord { address, tcp_port, udp_port, id: rng.gen() }
 }
 
+/// Generates a random IPv6 [`NodeRecord`] using the provided random number generator.
 pub fn rng_ipv6_record(rng: &mut impl RngCore) -> NodeRecord {
     let mut ip = [0u8; 16];
     rng.fill_bytes(&mut ip);
     let address = IpAddr::V6(ip.into());
     NodeRecord { address, tcp_port: rng.gen(), udp_port: rng.gen(), id: rng.gen() }
 }
 
+/// Generates a random IPv4 [`NodeRecord`] using the provided random number generator.
 pub fn rng_ipv4_record(rng: &mut impl RngCore) -> NodeRecord {
     let mut ip = [0u8; 4];
     rng.fill_bytes(&mut ip);
     let address = IpAddr::V4(ip.into());
     NodeRecord { address, tcp_port: rng.gen(), udp_port: rng.gen(), id: rng.gen() }
 }
 
+/// Generates a random [`Message`] using the provided random number generator.
 pub fn rng_message(rng: &mut impl RngCore) -> Message {
     match rng.gen_range(1..=4) {
         1 => Message::Ping(Ping {