add missing documentation for various crates (#5950)

crates/net/discv4/src/error.rs

@@ -4,17 +4,26 @@ use tokio::sync::{mpsc::error::SendError, oneshot::error::RecvError};
 
 /// Error thrown when decoding a UDP packet.
 #[derive(Debug, thiserror::Error)]
-#[allow(missing_docs)]
 pub enum DecodePacketError {
+    /// Failed to RLP decode the packet.
     #[error("failed to rlp decode: {0}")]
+    /// Indicates a failure to RLP decode the packet.
     Rlp(#[from] alloy_rlp::Error),
+    /// Received packet length is too short.
     #[error("received packet length is too short")]
+    /// Indicates the received packet length is insufficient.
     PacketTooShort,
+    /// Header/data hash mismatch.
     #[error("header/data hash mismatch")]
+    /// Indicates a mismatch between header and data hashes.
     HashMismatch,
+    /// Unsupported message ID.
     #[error("message ID {0} is not supported")]
+    /// Indicates an unsupported message ID.
     UnknownMessage(u8),
+    /// Failed to recover public key.
     #[error("failed to recover public key: {0}")]
+    /// Indicates a failure to recover the public key.
     Secp256k1(#[from] secp256k1::Error),
 }
 

crates/net/dns/src/error.rs

@@ -3,38 +3,59 @@ use crate::tree::TreeRootEntry;
 /// Alias for a parse result
 pub(crate) type ParseEntryResult<T> = Result<T, ParseDnsEntryError>;
 
+/// Alias for lookup results
 pub(crate) type LookupResult<T> = Result<T, LookupError>;
 
 /// Error while parsing a [DnsEntry](crate::tree::DnsEntry)
 #[derive(thiserror::Error, Debug)]
-#[allow(missing_docs)]
 pub enum ParseDnsEntryError {
+    /// Unknown entry error.
     #[error("unknown entry: {0}")]
+    /// Indicates an unknown entry encountered during parsing.
     UnknownEntry(String),
+    /// Field not found error.
     #[error("field {0} not found")]
+    /// Indicates a field was not found during parsing.
     FieldNotFound(&'static str),
+    /// Base64 decoding error.
     #[error("base64 decoding failed: {0}")]
+    /// Indicates a failure during Base64 decoding.
     Base64DecodeError(String),
+    /// Base32 decoding error.
     #[error("base32 decoding failed: {0}")]
+    /// Indicates a failure during Base32 decoding.
     Base32DecodeError(String),
+    /// RLP decoding error.
     #[error("{0}")]
+    /// Indicates an error during RLP decoding.
     RlpDecodeError(String),
+    /// Invalid child hash error in a branch.
     #[error("invalid child hash in branch: {0}")]
+    /// Indicates an invalid child hash within a branch.
     InvalidChildHash(String),
+    /// Other error.
     #[error("{0}")]
+    /// Indicates other unspecified errors.
     Other(String),
 }
 
 /// Errors that can happen during lookups
 #[derive(thiserror::Error, Debug)]
-#[allow(missing_docs)]
 pub(crate) enum LookupError {
+    /// Parse error.
     #[error(transparent)]
+    /// Represents errors during parsing.
     Parse(#[from] ParseDnsEntryError),
+    /// Invalid root error.
     #[error("failed to verify root {0}")]
+    /// Indicates failure while verifying the root entry.
     InvalidRoot(TreeRootEntry),
+    /// Request timed out error.
     #[error("request timed out")]
+    /// Indicates a timeout occurred during the request.
     RequestTimedOut,
+    /// Entry not found error.
     #[error("entry not found")]
+    /// Indicates the requested entry was not found.
     EntryNotFound,
 }

crates/net/network-api/src/error.rs

@@ -2,9 +2,9 @@ use thiserror::Error;
 use tokio::sync::{mpsc, oneshot};
 
 /// Network Errors
-#[allow(missing_docs)]
 #[derive(Error, Debug, Clone, PartialEq, Eq)]
 pub enum NetworkError {
+    /// Indicates that the sender has been dropped.
     #[error("sender has been dropped")]
     ChannelClosed,
 }

crates/net/network/src/message.rs

@@ -61,45 +61,66 @@ pub enum PeerMessage {
 
 /// Request Variants that only target block related data.
 #[derive(Debug, Clone, PartialEq, Eq)]
-#[allow(missing_docs)]
 pub enum BlockRequest {
+    /// Requests block headers from the peer.
+    ///
+    /// The response should be sent through the channel.
     GetBlockHeaders(GetBlockHeaders),
+
+    /// Requests block bodies from the peer.
+    ///
+    /// The response should be sent through the channel.
     GetBlockBodies(GetBlockBodies),
 }
 
 /// Protocol related request messages that expect a response
 #[derive(Debug)]
-#[allow(missing_docs)]
 pub enum PeerRequest {
-    /// Request Block headers from the peer.
+    /// Requests block headers from the peer.
     ///
     /// The response should be sent through the channel.
     GetBlockHeaders {
+        /// The request for block headers.
         request: GetBlockHeaders,
+        /// The channel to send the response for block headers.
         response: oneshot::Sender<RequestResult<BlockHeaders>>,
     },
-    /// Request Block headers from the peer.
+    /// Requests block bodies from the peer.
     ///
     /// The response should be sent through the channel.
     GetBlockBodies {
+        /// The request for block bodies.
         request: GetBlockBodies,
+        /// The channel to send the response for block bodies.
         response: oneshot::Sender<RequestResult<BlockBodies>>,
     },
-    /// Request pooled transactions from the peer.
+    /// Requests pooled transactions from the peer.
     ///
     /// The response should be sent through the channel.
     GetPooledTransactions {
+        /// The request for pooled transactions.
         request: GetPooledTransactions,
+        /// The channel to send the response for pooled transactions.
         response: oneshot::Sender<RequestResult<PooledTransactions>>,
     },
-    /// Request NodeData from the peer.
+    /// Requests NodeData from the peer.
     ///
     /// The response should be sent through the channel.
-    GetNodeData { request: GetNodeData, response: oneshot::Sender<RequestResult<NodeData>> },
-    /// Request Receipts from the peer.
+    GetNodeData {
+        /// The request for NodeData.
+        request: GetNodeData,
+        /// The channel to send the response for NodeData.
+        response: oneshot::Sender<RequestResult<NodeData>>,
+    },
+    /// Requests receipts from the peer.
     ///
     /// The response should be sent through the channel.
-    GetReceipts { request: GetReceipts, response: oneshot::Sender<RequestResult<Receipts>> },
+    GetReceipts {
+        /// The request for receipts.
+        request: GetReceipts,
+        /// The channel to send the response for receipts.
+        response: oneshot::Sender<RequestResult<Receipts>>,
+    },
 }
 
 // === impl PeerRequest ===
@@ -156,18 +177,32 @@ impl PeerRequest {
 
 /// Corresponding variant for [`PeerRequest`].
 #[derive(Debug)]
-#[allow(missing_docs)]
 pub enum PeerResponse {
-    /// Response to a [`GetBlockHeaders`] request.
-    BlockHeaders { response: oneshot::Receiver<RequestResult<BlockHeaders>> },
-    /// Response to a [`GetBlockBodies`] request.
-    BlockBodies { response: oneshot::Receiver<RequestResult<BlockBodies>> },
-    /// Response to a [`GetPooledTransactions`] request.
-    PooledTransactions { response: oneshot::Receiver<RequestResult<PooledTransactions>> },
-    /// Response to a [`GetNodeData`] request.
-    NodeData { response: oneshot::Receiver<RequestResult<NodeData>> },
-    /// Response to a [`GetReceipts`] request.
-    Receipts { response: oneshot::Receiver<RequestResult<Receipts>> },
+    /// Represents a response to a request for block headers.
+    BlockHeaders {
+        /// The receiver channel for the response to a block headers request.
+        response: oneshot::Receiver<RequestResult<BlockHeaders>>,
+    },
+    /// Represents a response to a request for block bodies.
+    BlockBodies {
+        /// The receiver channel for the response to a block bodies request.
+        response: oneshot::Receiver<RequestResult<BlockBodies>>,
+    },
+    /// Represents a response to a request for pooled transactions.
+    PooledTransactions {
+        /// The receiver channel for the response to a pooled transactions request.
+        response: oneshot::Receiver<RequestResult<PooledTransactions>>,
+    },
+    /// Represents a response to a request for NodeData.
+    NodeData {
+        /// The receiver channel for the response to a NodeData request.
+        response: oneshot::Receiver<RequestResult<NodeData>>,
+    },
+    /// Represents a response to a request for receipts.
+    Receipts {
+        /// The receiver channel for the response to a receipts request.
+        response: oneshot::Receiver<RequestResult<Receipts>>,
+    },
 }
 
 // === impl PeerResponse ===
@@ -207,12 +242,16 @@ impl PeerResponse {
 
 /// All response variants for [`PeerResponse`]
 #[derive(Debug)]
-#[allow(missing_docs)]
 pub enum PeerResponseResult {
+    /// Represents a result containing block headers or an error.
     BlockHeaders(RequestResult<Vec<Header>>),
+    /// Represents a result containing block bodies or an error.
     BlockBodies(RequestResult<Vec<BlockBody>>),
+    /// Represents a result containing pooled transactions or an error.
     PooledTransactions(RequestResult<Vec<PooledTransactionsElement>>),
+    /// Represents a result containing node data or an error.
     NodeData(RequestResult<Vec<Bytes>>),
+    /// Represents a result containing receipts or an error.
     Receipts(RequestResult<Vec<Vec<ReceiptWithBloom>>>),
 }
 

crates/net/network/src/network.rs

@@ -376,52 +376,64 @@ pub trait NetworkProtocols: Send + Sync {
 }
 
 /// Internal messages that can be passed to the  [`NetworkManager`](crate::NetworkManager).
-#[allow(missing_docs)]
 #[derive(Debug)]
 pub(crate) enum NetworkHandleMessage {
-    /// Adds an address for a peer.
+    /// Adds an address for a peer, including its ID, kind, and socket address.
     AddPeerAddress(PeerId, PeerKind, SocketAddr),
     /// Removes a peer from the peerset corresponding to the given kind.
     RemovePeer(PeerId, PeerKind),
-    /// Disconnect a connection to a peer if it exists.
+    /// Disconnects a connection to a peer if it exists, optionally providing a disconnect reason.
     DisconnectPeer(PeerId, Option<DisconnectReason>),
-    /// Add a new listener for [`NetworkEvent`].
+    /// Adds a new listener for `NetworkEvent`.
     EventListener(UnboundedSender<NetworkEvent>),
-    /// Broadcast event to announce a new block to all nodes.
+    /// Broadcasts an event to announce a new block to all nodes.
     AnnounceBlock(NewBlock, B256),
-    /// Sends the list of transactions to the given peer.
-    SendTransaction { peer_id: PeerId, msg: SharedTransactions },
-    /// Sends the list of transactions hashes to the given peer.
-    SendPooledTransactionHashes { peer_id: PeerId, msg: NewPooledTransactionHashes },
-    /// Send an `eth` protocol request to the peer.
+    /// Sends a list of transactions to the given peer.
+    SendTransaction {
+        /// The ID of the peer to which the transactions are sent.
+        peer_id: PeerId,
+        /// The shared transactions to send.
+        msg: SharedTransactions,
+    },
+    /// Sends a list of transaction hashes to the given peer.
+    SendPooledTransactionHashes {
+        /// The ID of the peer to which the transaction hashes are sent.
+        peer_id: PeerId,
+        /// The new pooled transaction hashes to send.
+        msg: NewPooledTransactionHashes,
+    },
+    /// Sends an `eth` protocol request to the peer.
     EthRequest {
         /// The peer to send the request to.
         peer_id: PeerId,
         /// The request to send to the peer's sessions.
         request: PeerRequest,
     },
-    /// Apply a reputation change to the given peer.
+    /// Applies a reputation change to the given peer.
     ReputationChange(PeerId, ReputationChangeKind),
     /// Returns the client that can be used to interact with the network.
     FetchClient(oneshot::Sender<FetchClient>),
-    /// Apply a status update.
-    StatusUpdate { head: Head },
-    /// Get the current status
+    /// Applies a status update.
+    StatusUpdate {
+        /// The head status to apply.
+        head: Head,
+    },
+    /// Retrieves the current status via a oneshot sender.
     GetStatus(oneshot::Sender<NetworkStatus>),
-    /// Get PeerInfo for the given peerids
+    /// Gets `PeerInfo` for the specified peer IDs.
     GetPeerInfosByIds(Vec<PeerId>, oneshot::Sender<Vec<PeerInfo>>),
-    /// Get PeerInfo from all the peers
+    /// Gets `PeerInfo` from all the peers via a oneshot sender.
     GetPeerInfos(oneshot::Sender<Vec<PeerInfo>>),
-    /// Get PeerInfo for a specific peer
+    /// Gets `PeerInfo` for a specific peer via a oneshot sender.
     GetPeerInfoById(PeerId, oneshot::Sender<Option<PeerInfo>>),
-    /// Get PeerInfo for a specific peer
+    /// Gets `PeerInfo` for a specific peer kind via a oneshot sender.
     GetPeerInfosByPeerKind(PeerKind, oneshot::Sender<Vec<PeerInfo>>),
-    /// Get the reputation for a specific peer
+    /// Gets the reputation for a specific peer via a oneshot sender.
     GetReputationById(PeerId, oneshot::Sender<Option<Reputation>>),
-    /// Gracefully shutdown network
+    /// Initiates a graceful shutdown of the network via a oneshot sender.
     Shutdown(oneshot::Sender<()>),
-    /// Add a new listener for `DiscoveryEvent`.
+    /// Adds a new listener for `DiscoveryEvent`.
     DiscoveryListener(UnboundedSender<DiscoveryEvent>),
-    /// Add an additional [RlpxSubProtocol].
+    /// Adds an additional `RlpxSubProtocol`.
     AddRlpxSubProtocol(RlpxSubProtocol),
 }

crates/net/network/src/transactions.rs

@@ -1255,18 +1255,30 @@ enum TransactionsCommand {
 
 /// All events related to transactions emitted by the network.
 #[derive(Debug)]
-#[allow(missing_docs)]
 pub enum NetworkTransactionEvent {
-    /// Received list of transactions from the given peer.
+    /// Represents the event of receiving a list of transactions from a peer.
     ///
-    /// This represents transactions that were broadcasted to use from the peer.
-    IncomingTransactions { peer_id: PeerId, msg: Transactions },
-    /// Received list of transactions hashes to the given peer.
-    IncomingPooledTransactionHashes { peer_id: PeerId, msg: NewPooledTransactionHashes },
-    /// Incoming `GetPooledTransactions` request from a peer.
-    GetPooledTransactions {
+    /// This indicates transactions that were broadcasted to us from the peer.
+    IncomingTransactions {
+        /// The ID of the peer from which the transactions were received.
         peer_id: PeerId,
+        /// The received transactions.
+        msg: Transactions,
+    },
+    /// Represents the event of receiving a list of transaction hashes from a peer.
+    IncomingPooledTransactionHashes {
+        /// The ID of the peer from which the transaction hashes were received.
+        peer_id: PeerId,
+        /// The received new pooled transaction hashes.
+        msg: NewPooledTransactionHashes,
+    },
+    /// Represents the event of receiving a `GetPooledTransactions` request from a peer.
+    GetPooledTransactions {
+        /// The ID of the peer from which the request was received.
+        peer_id: PeerId,
+        /// The received `GetPooledTransactions` request.
         request: GetPooledTransactions,
+        /// The sender for responding to the request with a result of `PooledTransactions`.
         response: oneshot::Sender<RequestResult<PooledTransactions>>,
     },
 }