diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cd6653550..ad9c21538 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -163,12 +163,22 @@ jobs: args: --all --all-features token: ${{ secrets.GITHUB_TOKEN }} - docs-test: + doc-test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install toolchain uses: dtolnay/rust-toolchain@stable - uses: Swatinem/rust-cache@v2 - - name: "test --doc --all --all-features" + - name: Run doctests run: cargo test --doc --all --all-features + + doc-lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Install toolchain + uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 + - name: Check if documentation builds + run: RUSTDOCFLAGS="-D warnings" cargo doc --all --no-deps --all-features --document-private-items diff --git a/bin/reth/src/db/mod.rs b/bin/reth/src/db/mod.rs index 19d64fca0..693a3aafc 100644 --- a/bin/reth/src/db/mod.rs +++ b/bin/reth/src/db/mod.rs @@ -214,7 +214,7 @@ impl<'a, DB: Database> DbTool<'a, DB> { } /// Grabs the contents of the table within a certain index range and places the - /// entries into a [HashMap]. + /// entries into a [`HashMap`][std::collections::HashMap]. fn list(&mut self, start: usize, len: usize) -> Result> { let data = self.db.view(|tx| { let mut cursor = tx.cursor_read::().expect("Was not able to obtain a cursor."); diff --git a/crate-template/src/lib.rs b/crate-template/src/lib.rs index f2bc06a4a..3a8c14f77 100644 --- a/crate-template/src/lib.rs +++ b/crate-template/src/lib.rs @@ -5,4 +5,4 @@ attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables)) ))] -//! +//! reth crate template diff --git a/crates/consensus/src/engine/error.rs b/crates/consensus/src/engine/error.rs index 88348f87a..5bfb14cfd 100644 --- a/crates/consensus/src/engine/error.rs +++ b/crates/consensus/src/engine/error.rs @@ -4,7 +4,7 @@ use thiserror::Error; /// The Engine API result type pub type EngineApiResult = Result; -/// Error returned by [`EngineApi`][crate::engine::EngineApi] +/// Error returned by [`EthConsensusEngine`][crate::engine::EthConsensusEngine] #[derive(Error, Debug)] pub enum EngineApiError { /// Invalid payload extra data. diff --git a/crates/consensus/src/engine/mod.rs b/crates/consensus/src/engine/mod.rs index 4392d9e37..fbc1989e3 100644 --- a/crates/consensus/src/engine/mod.rs +++ b/crates/consensus/src/engine/mod.rs @@ -112,7 +112,8 @@ impl EthConsensusEngine< /// NOTE: The log bloom is assumed to be validated during serialization. /// NOTE: Empty ommers, nonce and difficulty values are validated upon computing block hash and /// comparing the value with `payload.block_hash`. - /// Ref: https://github.com/ethereum/go-ethereum/blob/79a478bb6176425c2400e949890e668a3d9a3d05/core/beacon/types.go#L145 + /// + /// See fn try_construct_block(&self, payload: ExecutionPayload) -> EngineApiResult { if payload.extra_data.len() > 32 { return Err(EngineApiError::PayloadExtraData(payload.extra_data)) diff --git a/crates/executor/src/eth_dao_fork.rs b/crates/executor/src/eth_dao_fork.rs index dcde57c0c..d4bff3414 100644 --- a/crates/executor/src/eth_dao_fork.rs +++ b/crates/executor/src/eth_dao_fork.rs @@ -1,4 +1,4 @@ -//! DAO FOrk related constants https://eips.ethereum.org/EIPS/eip-779 +//! DAO FOrk related constants from [EIP-779](https://eips.ethereum.org/EIPS/eip-779). //! It happened on Ethereum block 1_920_000 use reth_primitives::{hex_literal::hex, H160}; diff --git a/crates/interfaces/src/consensus.rs b/crates/interfaces/src/consensus.rs index 9b96cd21e..effebe473 100644 --- a/crates/interfaces/src/consensus.rs +++ b/crates/interfaces/src/consensus.rs @@ -3,7 +3,7 @@ use reth_primitives::{BlockHash, BlockNumber, SealedBlock, SealedHeader, H256}; use std::fmt::Debug; use tokio::sync::watch::{error::SendError, Receiver}; -/// Re-export forkchoice state +/// Re-export fork choice state pub use reth_rpc_types::engine::ForkchoiceState; /// Consensus is a protocol that chooses canonical chain. @@ -34,10 +34,10 @@ pub trait Consensus: Debug + Send + Sync { fn pre_validate_block(&self, block: &SealedBlock) -> Result<(), Error>; /// After the Merge (aka Paris) block rewards became obsolete. - /// This flag is needed as reth change set is indexed of transaction granularity - /// (change set is indexed per transaction) we are introducing one additional index for block - /// reward This in essence would introduce gaps in [Transaction] table - /// More on it [here](https://github.com/paradigmxyz/reth/issues/237) + /// + /// This flag is needed as reth's changeset is indexed on transaction level granularity. + /// + /// More info [here](https://github.com/paradigmxyz/reth/issues/237) fn has_block_reward(&self, block_num: BlockNumber) -> bool; } diff --git a/crates/interfaces/src/p2p/bodies/downloader.rs b/crates/interfaces/src/p2p/bodies/downloader.rs index 07e1211a0..69c6c461a 100644 --- a/crates/interfaces/src/p2p/bodies/downloader.rs +++ b/crates/interfaces/src/p2p/bodies/downloader.rs @@ -10,7 +10,8 @@ pub type BodyDownloaderResult = DownloadResult>; /// A downloader capable of fetching and yielding block bodies from block headers. /// /// A downloader represents a distinct strategy for submitting requests to download block bodies, -/// while a [BodiesClient] represents a client capable of fulfilling these requests. +/// while a [BodiesClient][crate::p2p::bodies::client::BodiesClient] represents a client capable of +/// fulfilling these requests. pub trait BodyDownloader: Send + Sync + Stream + Unpin { /// Method for setting the download range. fn set_download_range(&mut self, range: Range) -> DownloadResult<()>; diff --git a/crates/interfaces/src/p2p/error.rs b/crates/interfaces/src/p2p/error.rs index f612aafe7..7275593a8 100644 --- a/crates/interfaces/src/p2p/error.rs +++ b/crates/interfaces/src/p2p/error.rs @@ -7,7 +7,7 @@ use tokio::sync::{mpsc, oneshot}; /// Result alias for result of a request. pub type RequestResult = Result; -/// Result with [PeerId] +/// Result with [PeerId][reth_primitives::PeerId] pub type PeerRequestResult = RequestResult>; /// Helper trait used to validate responses. diff --git a/crates/interfaces/src/p2p/headers/downloader.rs b/crates/interfaces/src/p2p/headers/downloader.rs index dba6f66fd..a7d0f45b9 100644 --- a/crates/interfaces/src/p2p/headers/downloader.rs +++ b/crates/interfaces/src/p2p/headers/downloader.rs @@ -8,7 +8,8 @@ use reth_primitives::{SealedHeader, H256}; /// A downloader capable of fetching and yielding block headers. /// /// A downloader represents a distinct strategy for submitting requests to download block headers, -/// while a [HeadersClient] represents a client capable of fulfilling these requests. +/// while a [HeadersClient][crate::p2p::headers::client::HeadersClient] represents a client capable +/// of fulfilling these requests. /// /// A [HeaderDownloader] is a [Stream] that returns batches for headers. pub trait HeaderDownloader: Send + Sync + Stream> + Unpin { diff --git a/crates/interfaces/src/p2p/mod.rs b/crates/interfaces/src/p2p/mod.rs index a3b96a8dc..fa7cabaa9 100644 --- a/crates/interfaces/src/p2p/mod.rs +++ b/crates/interfaces/src/p2p/mod.rs @@ -9,7 +9,7 @@ pub mod bodies; /// [`HeadersClient`]. /// /// [`Consensus`]: crate::consensus::Consensus -/// [`HeadersClient`]: crate::p2p::headers::HeadersClient +/// [`HeadersClient`]: crate::p2p::headers::client::HeadersClient pub mod headers; /// Error types broadly used by p2p interfaces for any operation which may produce an error when diff --git a/crates/interfaces/src/test_utils/generators.rs b/crates/interfaces/src/test_utils/generators.rs index d6e6c2e65..dbcc1b492 100644 --- a/crates/interfaces/src/test_utils/generators.rs +++ b/crates/interfaces/src/test_utils/generators.rs @@ -59,7 +59,7 @@ pub fn random_tx() -> Transaction { /// Generates a random legacy [Transaction] that is signed. /// -/// On top of the considerations of [gen_random_tx], these apply as well: +/// On top of the considerations of [random_tx], these apply as well: /// /// - There is no guarantee that the nonce is not used twice for the same account pub fn random_signed_tx() -> TransactionSigned { diff --git a/crates/metrics/metrics-derive/src/expand.rs b/crates/metrics/metrics-derive/src/expand.rs index 0b67eb783..eab7c8a37 100644 --- a/crates/metrics/metrics-derive/src/expand.rs +++ b/crates/metrics/metrics-derive/src/expand.rs @@ -9,7 +9,8 @@ use syn::{ use crate::{metric::Metric, with_attrs::WithAttrs}; /// Metric name regex according to Prometheus data model -/// https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels +/// +/// See static METRIC_NAME_RE: Lazy = Lazy::new(|| Regex::new(r"^[a-zA-Z_:.][a-zA-Z0-9_:.]*$").unwrap()); @@ -27,7 +28,8 @@ pub(crate) fn derive(node: &DeriveInput) -> Result { let describe_doc = quote! { /// Describe all exposed metrics. Internally calls `describe_*` macros from /// the metrics crate according to the metric type. - /// Ref: https://docs.rs/metrics/0.20.1/metrics/index.html#macros + /// + /// See }; let register_and_describe = match &metrics_attr.scope { MetricsScope::Static(scope) => { diff --git a/crates/net/common/src/bandwidth_meter.rs b/crates/net/common/src/bandwidth_meter.rs index c98f90971..349c9ccd8 100644 --- a/crates/net/common/src/bandwidth_meter.rs +++ b/crates/net/common/src/bandwidth_meter.rs @@ -1,4 +1,6 @@ -//! Support for metering bandwidth. Takes heavy inspiration from https://github.com/libp2p/rust-libp2p/blob/master/src/bandwidth.rs +//! Support for metering bandwidth. +//! +//! Takes heavy inspiration from // Copyright 2019 Parity Technologies (UK) Ltd. // diff --git a/crates/net/discv4/src/config.rs b/crates/net/discv4/src/config.rs index 510ec4900..7636047cf 100644 --- a/crates/net/discv4/src/config.rs +++ b/crates/net/discv4/src/config.rs @@ -1,7 +1,7 @@ //! A set of configuration parameters to tune the discovery protocol. //! //! This basis of this file has been taken from the discv5 codebase: -//! https://github.com/sigp/discv5 +//! use bytes::{Bytes, BytesMut}; use reth_net_common::ban_list::BanList; diff --git a/crates/net/dns/src/config.rs b/crates/net/dns/src/config.rs index 26df6886f..e5961f600 100644 --- a/crates/net/dns/src/config.rs +++ b/crates/net/dns/src/config.rs @@ -3,7 +3,7 @@ use serde::{Deserialize, Serialize}; use crate::tree::LinkEntry; use std::{collections::HashSet, num::NonZeroUsize, time::Duration}; -/// Settings for the [DnsDiscoveryClient](crate::DnsDiscoveryClient). +/// Settings for the [DnsDiscoveryService](crate::DnsDiscoveryService). #[derive(Debug, Clone, Serialize, Deserialize)] pub struct DnsDiscoveryConfig { /// Timeout for DNS lookups. diff --git a/crates/net/dns/src/error.rs b/crates/net/dns/src/error.rs index 3b6d6bf85..d7b0a53c0 100644 --- a/crates/net/dns/src/error.rs +++ b/crates/net/dns/src/error.rs @@ -5,7 +5,7 @@ pub(crate) type ParseEntryResult = Result; pub(crate) type LookupResult = Result; -/// Error while parsing a [DnsEntry] +/// Error while parsing a [DnsEntry](crate::tree::DnsEntry) #[derive(thiserror::Error, Debug)] #[allow(missing_docs)] pub enum ParseDnsEntryError { diff --git a/crates/net/downloaders/src/bodies/concurrent.rs b/crates/net/downloaders/src/bodies/concurrent.rs index c3bf002b7..cbf6d0ff6 100644 --- a/crates/net/downloaders/src/bodies/concurrent.rs +++ b/crates/net/downloaders/src/bodies/concurrent.rs @@ -408,8 +408,8 @@ where } } -/// SAFETY: we need to ensure `ConcurrentDownloader` is `Sync` because the of the [Downloader] -/// trait. While [HeadersClient] is also `Sync`, the [HeadersClient::get_block_bodies] future does +/// SAFETY: we need to ensure `ConcurrentDownloader` is `Sync` because the of the [BodyDownloader] +/// trait. While [BodiesClient] is also `Sync`, the [BodiesClient::get_block_bodies] future does /// not enforce `Sync` (async_trait). The future itself does not use any interior mutability /// whatsoever: All the mutations are performed through an exclusive reference on /// `ConcurrentDownloader` when the Stream is polled. This means it suffices that diff --git a/crates/net/downloaders/src/bodies/request.rs b/crates/net/downloaders/src/bodies/request.rs index 22ae9c3a2..3bb3dc28a 100644 --- a/crates/net/downloaders/src/bodies/request.rs +++ b/crates/net/downloaders/src/bodies/request.rs @@ -26,9 +26,9 @@ type BodiesFut = Pin>> /// It then proceeds to verify the downloaded bodies. In case of an validation error, /// the future will start over. /// -/// The future will filter out any empty headers (see [SealedHeader::is_empty]) from the request. -/// If [BodiesRequestFuture] was initialized with all empty headers, no request will be dispatched -/// and they will be immediately returned upon polling. +/// The future will filter out any empty headers (see [reth_primitives::Header::is_empty]) from the +/// request. If [BodiesRequestFuture] was initialized with all empty headers, no request will be +/// dispatched and they will be immediately returned upon polling. /// /// NB: This assumes that peers respond with bodies in the order that they were requested. /// This is a reasonable assumption to make as that's [what Geth diff --git a/crates/net/downloaders/src/headers/linear.rs b/crates/net/downloaders/src/headers/linear.rs index a0baea960..909ac1fe0 100644 --- a/crates/net/downloaders/src/headers/linear.rs +++ b/crates/net/downloaders/src/headers/linear.rs @@ -35,7 +35,7 @@ pub const HEADERS_DOWNLOADER_SCOPE: &str = "downloaders.headers"; /// Downloads headers concurrently. /// -/// This [Downloader] downloads headers using the configured [HeadersClient]. +/// This [HeaderDownloader] downloads headers using the configured [HeadersClient]. /// Headers can be requested by hash or block number and take a `limit` parameter. This downloader /// tries to fill the gap between the local head of the node and the chain tip by issuing multiple /// requests at a time but yielding them in batches on [Stream::poll_next]. @@ -689,7 +689,7 @@ where } } -/// SAFETY: we need to ensure `LinearDownloader` is `Sync` because the of the [Downloader] +/// SAFETY: we need to ensure `LinearDownloader` is `Sync` because the of the [HeaderDownloader] /// trait. While [HeadersClient] is also `Sync`, the [HeadersClient::get_headers] future does not /// enforce `Sync` (async_trait). The future itself does not use any interior mutability whatsoever: /// All the mutations are performed through an exclusive reference on `LinearDownloader` when diff --git a/crates/net/eth-wire/src/builder.rs b/crates/net/eth-wire/src/builder.rs index e434fff49..53b29a81a 100644 --- a/crates/net/eth-wire/src/builder.rs +++ b/crates/net/eth-wire/src/builder.rs @@ -1,5 +1,5 @@ -//! Builder structs for [`Status`](crate::types::Status) and [`Hello`](crate::types::Hello) -//! messages. +//! Builder structs for [`Status`](crate::types::Status) and +//! [`HelloMessage`](crate::HelloMessage) messages. use crate::{ capability::Capability, hello::HelloMessage, p2pstream::ProtocolVersion, EthVersion, Status, @@ -84,14 +84,14 @@ impl StatusBuilder { } } -/// Builder for [`Hello`](crate::types::Hello) messages. +/// Builder for [`HelloMessage`](crate::HelloMessage) messages. pub struct HelloBuilder { hello: HelloMessage, } impl HelloBuilder { - /// Creates a new [`HelloBuilder`](crate::builder::HelloBuilder) with default [`Hello`] values, - /// and a `PeerId` corresponding to the given pubkey. + /// Creates a new [`HelloBuilder`](crate::builder::HelloBuilder) with default [`HelloMessage`] + /// values, and a `PeerId` corresponding to the given pubkey. pub fn new(pubkey: PeerId) -> Self { Self { hello: HelloMessage { @@ -106,7 +106,7 @@ impl HelloBuilder { } } - /// Consumes the type and creates the actual [`Hello`](crate::types::Hello) message. + /// Consumes the type and creates the actual [`HelloMessage`] message. pub fn build(self) -> HelloMessage { self.hello } diff --git a/crates/net/eth-wire/src/errors/p2p.rs b/crates/net/eth-wire/src/errors/p2p.rs index 93562c2c6..3d7a2e7f0 100644 --- a/crates/net/eth-wire/src/errors/p2p.rs +++ b/crates/net/eth-wire/src/errors/p2p.rs @@ -76,7 +76,7 @@ pub enum P2PHandshakeError { DecodeError(#[from] reth_rlp::DecodeError), } -/// An error that can occur when interacting with a [`Pinger`]. +/// An error that can occur when interacting with a pinger. #[derive(Debug, thiserror::Error)] pub enum PingerError { /// An unexpected pong was received while the pinger was in the `Ready` state. diff --git a/crates/net/eth-wire/src/hello.rs b/crates/net/eth-wire/src/hello.rs index 416da853a..1a0f584d9 100644 --- a/crates/net/eth-wire/src/hello.rs +++ b/crates/net/eth-wire/src/hello.rs @@ -29,7 +29,7 @@ pub struct HelloMessage { // === impl HelloMessage === impl HelloMessage { - /// Starts a new [`HelloMessageBuilder`] + /// Starts a new `HelloMessageBuilder` /// /// ``` /// use secp256k1::{SECP256K1, SecretKey}; diff --git a/crates/net/eth-wire/src/p2pstream.rs b/crates/net/eth-wire/src/p2pstream.rs index ad87c5668..fc1cfc577 100644 --- a/crates/net/eth-wire/src/p2pstream.rs +++ b/crates/net/eth-wire/src/p2pstream.rs @@ -624,10 +624,10 @@ pub enum P2PMessage { /// immediately. Disconnect(DisconnectReason), - /// Requests an immediate reply of [`Pong`] from the peer. + /// Requests an immediate reply of [`P2PMessage::Pong`] from the peer. Ping, - /// Reply to the peer's [`Ping`] packet. + /// Reply to the peer's [`P2PMessage::Ping`] packet. Pong, } diff --git a/crates/net/eth-wire/src/pinger.rs b/crates/net/eth-wire/src/pinger.rs index e8ef15a3c..1d1898abe 100644 --- a/crates/net/eth-wire/src/pinger.rs +++ b/crates/net/eth-wire/src/pinger.rs @@ -112,11 +112,12 @@ pub(crate) enum PingState { TimedOut, } -/// The element type produced by a [`IntervalPingerStream`], representing either a new [`Ping`] +/// The element type produced by a [`Pinger`], representing either a new +/// [`Ping`](super::P2PMessage::Ping) /// message to send, or an indication that the peer should be timed out. #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) enum PingerEvent { - /// A new [`Ping`] message should be sent. + /// A new [`Ping`](super::P2PMessage::Ping) message should be sent. Ping, /// The peer should be timed out. diff --git a/crates/net/eth-wire/src/types/blocks.rs b/crates/net/eth-wire/src/types/blocks.rs index c734280d8..260a55fe4 100644 --- a/crates/net/eth-wire/src/types/blocks.rs +++ b/crates/net/eth-wire/src/types/blocks.rs @@ -98,7 +98,7 @@ pub struct BlockBody { } impl BlockBody { - /// Create a [`Block`] from the body and its header. + /// Create a [`RawBlockBody`] from the body and its header. pub fn create_block(&self, header: &Header) -> RawBlockBody { RawBlockBody { header: header.clone(), diff --git a/crates/net/ipc/src/server/mod.rs b/crates/net/ipc/src/server/mod.rs index f8d6fcda1..e6f46fe1c 100644 --- a/crates/net/ipc/src/server/mod.rs +++ b/crates/net/ipc/src/server/mod.rs @@ -217,7 +217,7 @@ pub(crate) struct ServiceData { /// JsonRPSee service compatible with `tower`. /// /// # Note -/// This is similar to [`hyper::service::service_fn`]. +/// This is similar to [`hyper::service::service_fn`](https://docs.rs/hyper/latest/hyper/service/fn.service_fn.html). #[derive(Debug)] pub struct TowerService { inner: ServiceData, @@ -430,8 +430,7 @@ impl Builder { /// registered resources on this server instance would exceed 8. /// /// See the module documentation for - /// [`resurce_limiting`](../jsonrpsee_utils/server/resource_limiting/index.html# - /// resource-limiting) for details. + /// [`resource_limiting`][jsonrpsee::core::server::resource_limiting] for details. pub fn register_resource( mut self, label: &'static str, diff --git a/crates/net/network/src/error.rs b/crates/net/network/src/error.rs index db260b8f2..887dff0a4 100644 --- a/crates/net/network/src/error.rs +++ b/crates/net/network/src/error.rs @@ -36,7 +36,7 @@ pub(crate) trait SessionError: fmt::Debug { /// /// Note: This does not necessarily mean that either of the peers are in violation of the /// protocol but rather that they'll never be able to connect with each other. This check is - /// a superset of [`error_merits_discovery_ban`] which checks if the peer should not be part + /// a superset of [`Self::merits_discovery_ban`] which checks if the peer should not be part /// of the gossip network. fn is_fatal_protocol_error(&self) -> bool; diff --git a/crates/net/network/src/lib.rs b/crates/net/network/src/lib.rs index dcccc4cd0..0ef25df71 100644 --- a/crates/net/network/src/lib.rs +++ b/crates/net/network/src/lib.rs @@ -21,7 +21,7 @@ //! The `Network` is made up of several, separate tasks: //! //! - `Transactions Task`: is a spawned -//! [`TransactionManager`](crate::transactions::TransactionsManager) future that: +//! [`TransactionsManager`](crate::transactions::TransactionsManager) future that: //! //! * Responds to incoming transaction related requests //! * Requests missing transactions from the `Network` diff --git a/crates/net/network/src/listener.rs b/crates/net/network/src/listener.rs index de152cf85..18fbf59bb 100644 --- a/crates/net/network/src/listener.rs +++ b/crates/net/network/src/listener.rs @@ -57,7 +57,7 @@ impl ConnectionListener { } } -/// Event type produced by the [`Transport`]. +/// Event type produced by the [`TcpListenerStream`]. pub enum ListenerEvent { /// Received a new incoming. Incoming { diff --git a/crates/net/network/src/manager.rs b/crates/net/network/src/manager.rs index 55f0210fa..8862e79c5 100644 --- a/crates/net/network/src/manager.rs +++ b/crates/net/network/src/manager.rs @@ -130,7 +130,7 @@ impl NetworkManager { &self.handle } - /// Returns a shareable reference to the [`BandwidthMeter`] stored on the [`NetworkInner`] + /// Returns a shareable reference to the [`BandwidthMeter`] stored /// inside of the [`NetworkHandle`] pub fn bandwidth_meter(&self) -> &BandwidthMeter { self.handle.bandwidth_meter() diff --git a/crates/net/network/src/metrics.rs b/crates/net/network/src/metrics.rs index b73d86e24..62e02ab75 100644 --- a/crates/net/network/src/metrics.rs +++ b/crates/net/network/src/metrics.rs @@ -33,7 +33,7 @@ pub struct NetworkMetrics { pub(crate) invalid_messages_received: Counter, } -/// Metrics for the TransactionManager +/// Metrics for the TransactionsManager #[derive(Metrics)] #[metrics(scope = "network")] pub struct TransactionsManagerMetrics { diff --git a/crates/net/network/src/network.rs b/crates/net/network/src/network.rs index 0c6dcde1c..a6e314290 100644 --- a/crates/net/network/src/network.rs +++ b/crates/net/network/src/network.rs @@ -260,7 +260,7 @@ impl SyncStateUpdater for NetworkHandle { struct NetworkInner { /// Number of active peer sessions the node's currently handling. num_active_peers: Arc, - /// Sender half of the message channel to the [`NetworkManager`]. + /// Sender half of the message channel to the [`crate::NetworkManager`]. to_manager_tx: UnboundedSender, /// The local address that accepts incoming connections. listener_address: Arc>, diff --git a/crates/net/network/src/peers/manager.rs b/crates/net/network/src/peers/manager.rs index 4ae7d793d..989a04d9c 100644 --- a/crates/net/network/src/peers/manager.rs +++ b/crates/net/network/src/peers/manager.rs @@ -604,7 +604,7 @@ impl PeersManager { /// Advances the state. /// /// Event hooks invoked externally may trigger a new [`PeerAction`] that are buffered until - /// [`PeersManager::poll_next`] is called. + /// [`PeersManager`] is polled. pub fn poll(&mut self, cx: &mut Context<'_>) -> Poll { loop { // drain buffered actions diff --git a/crates/net/network/src/session/active.rs b/crates/net/network/src/session/active.rs index 8e5055429..d2b9cc62c 100644 --- a/crates/net/network/src/session/active.rs +++ b/crates/net/network/src/session/active.rs @@ -39,10 +39,11 @@ use tokio_stream::wrappers::ReceiverStream; use tracing::{debug, error, info, trace, warn}; /// The type that advances an established session by listening for incoming messages (from local -/// node or read from connection) and emitting events back to the [`SessionsManager`]. +/// node or read from connection) and emitting events back to the +/// [`SessionManager`](super::SessionManager). /// /// It listens for -/// - incoming commands from the [`SessionsManager`] +/// - incoming commands from the [`SessionManager`](super::SessionManager) /// - incoming requests via the request channel /// - responses for handled ETH requests received from the remote peer. #[allow(unused)] @@ -61,7 +62,7 @@ pub(crate) struct ActiveSession { pub(crate) session_id: SessionId, /// Incoming commands from the manager pub(crate) commands_rx: ReceiverStream, - /// Sink to send messages to the [`SessionManager`]. + /// Sink to send messages to the [`SessionManager`](super::SessionManager). pub(crate) to_session: mpsc::Sender, /// Incoming request to send to delegate to the remote peer. pub(crate) request_tx: Fuse>, @@ -257,7 +258,7 @@ impl ActiveSession { } } - /// Send a message back to the [`SessionsManager`] + /// Send a message back to the [`SessionManager`](super::SessionManager) fn emit_message(&self, message: PeerMessage) { let _ = self.try_emit_message(message).map_err(|err| { warn!( @@ -268,7 +269,7 @@ impl ActiveSession { }); } - /// Send a message back to the [`SessionsManager`] + /// Send a message back to the [`SessionManager`](super::SessionManager) /// covering both broadcasts and incoming requests fn safe_emit_message( &self, @@ -280,7 +281,7 @@ impl ActiveSession { .try_send(ActiveSessionMessage::ValidMessage { peer_id: self.remote_peer_id, message }) } - /// Send a message back to the [`SessionsManager`] + /// Send a message back to the [`SessionManager`](super::SessionManager) fn try_emit_message( &self, message: PeerMessage, diff --git a/crates/net/network/src/session/mod.rs b/crates/net/network/src/session/mod.rs index 523f276f2..47baf4350 100644 --- a/crates/net/network/src/session/mod.rs +++ b/crates/net/network/src/session/mod.rs @@ -83,12 +83,12 @@ pub(crate) struct SessionManager { pending_sessions_tx: mpsc::Sender, /// Receiver half that listens for [`PendingSessionEvent`] produced by pending sessions. pending_session_rx: ReceiverStream, - /// The original Sender half of the [`ActiveSessionEvent`] channel. + /// The original Sender half of the [`ActiveSessionMessage`] channel. /// /// When active session state is reached, the corresponding [`ActiveSessionHandle`] will get a /// clone of this sender half. active_session_tx: mpsc::Sender, - /// Receiver half that listens for [`ActiveSessionEvent`] produced by pending sessions. + /// Receiver half that listens for [`ActiveSessionMessage`] produced by pending sessions. active_session_rx: ReceiverStream, /// Used to measure inbound & outbound bandwidth across all managed streams bandwidth_meter: BandwidthMeter, @@ -153,7 +153,8 @@ impl SessionManager { self.hello_message.clone() } - /// Spawns the given future onto a new task that is tracked in the `spawned_tasks` [`JoinSet`]. + /// Spawns the given future onto a new task that is tracked in the `spawned_tasks` + /// [`JoinSet`](tokio::task::JoinSet). fn spawn(&self, f: F) where F: Future + Send + 'static, diff --git a/crates/net/network/src/state.rs b/crates/net/network/src/state.rs index 792d99314..707d6214d 100644 --- a/crates/net/network/src/state.rs +++ b/crates/net/network/src/state.rs @@ -465,7 +465,7 @@ pub(crate) struct ActivePeer { pub(crate) blocks: LruCache, } -/// Message variants triggered by the [`State`] +/// Message variants triggered by the [`NetworkState`] pub(crate) enum StateAction { /// Dispatch a `NewBlock` message to the peer NewBlock { diff --git a/crates/net/network/src/swarm.rs b/crates/net/network/src/swarm.rs index 0497b4e8a..5b790abc9 100644 --- a/crates/net/network/src/swarm.rs +++ b/crates/net/network/src/swarm.rs @@ -266,9 +266,10 @@ where /// This advances all components. /// - /// Processes, delegates (internal) commands received from the [`NetworkManager`], then polls - /// the [`SessionManager`] which yields messages produced by individual peer sessions that are - /// then handled. Least priority are incoming connections that are handled and delegated to + /// Processes, delegates (internal) commands received from the + /// [`NetworkManager`](crate::NetworkManager), then polls the [`SessionManager`] which + /// yields messages produced by individual peer sessions that are then handled. Least + /// priority are incoming connections that are handled and delegated to /// the [`SessionManager`] to turn them into a session. fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll> { let this = self.get_mut(); diff --git a/crates/net/network/src/test_utils/testnet.rs b/crates/net/network/src/test_utils/testnet.rs index 462c77b41..3834fb8e9 100644 --- a/crates/net/network/src/test_utils/testnet.rs +++ b/crates/net/network/src/test_utils/testnet.rs @@ -338,8 +338,9 @@ impl NetworkEventStream { None } - /// Ensures that the first two events are a [`PeerAdded`] and [`SessionEstablished`], - /// returning the [`PeerId`] of the established session. + /// Ensures that the first two events are a [`NetworkEvent::PeerAdded`] and + /// [`NetworkEvent::SessionEstablished`], returning the [`PeerId`] of the established + /// session. pub async fn peer_added_and_established(&mut self) -> Option { let peer_id = match self.inner.next().await { Some(NetworkEvent::PeerAdded(peer_id)) => peer_id, diff --git a/crates/net/network/src/transactions.rs b/crates/net/network/src/transactions.rs index f8718e20c..c51708c61 100644 --- a/crates/net/network/src/transactions.rs +++ b/crates/net/network/src/transactions.rs @@ -534,7 +534,7 @@ struct Peer { request_tx: PeerRequestSender, } -/// Commands to send to the [`TransactionManager`] +/// Commands to send to the [`TransactionsManager`](crate::transactions::TransactionsManager) enum TransactionsCommand { PropagateHash(H256), } diff --git a/crates/net/rpc-types/src/admin.rs b/crates/net/rpc-types/src/admin.rs index 9274be193..bdc57c9b2 100644 --- a/crates/net/rpc-types/src/admin.rs +++ b/crates/net/rpc-types/src/admin.rs @@ -6,8 +6,8 @@ use std::net::{IpAddr, SocketAddr}; /// Represents the `admin_nodeInfo` response, which can be queried for all the information /// known about the running node at the networking granularity. /// -/// Note: this format is not standardized. Reth follows geth's format, -/// see: https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-admin +/// Note: this format is not standardized. Reth follows Geth's format, +/// see: #[derive(Serialize, Deserialize, Debug)] pub struct NodeInfo { /// Enode in URL format. diff --git a/crates/net/rpc-types/src/eth/trace/parity.rs b/crates/net/rpc-types/src/eth/trace/parity.rs index d41649ec1..80c435979 100644 --- a/crates/net/rpc-types/src/eth/trace/parity.rs +++ b/crates/net/rpc-types/src/eth/trace/parity.rs @@ -1,5 +1,7 @@ #![allow(missing_docs)] -//! Types for trace module: Ref https://openethereum.github.io/JSONRPC-trace-module +//! Types for trace module. +//! +//! See use reth_primitives::{Address, Bytes, H256, U256, U64}; use serde::{Deserialize, Serialize}; diff --git a/crates/net/rpc-types/src/eth/transaction/typed.rs b/crates/net/rpc-types/src/eth/transaction/typed.rs index 2d71acf5e..e5117cead 100644 --- a/crates/net/rpc-types/src/eth/transaction/typed.rs +++ b/crates/net/rpc-types/src/eth/transaction/typed.rs @@ -1,7 +1,7 @@ #![allow(missing_docs)] -//! The [`TransactionRequest`] is a universal representation for a transaction deserialized from the -//! json input of an RPC call. Depending on what fields are set, it can be converted into the -//! container type [`TypedTransactionRequest`]. +//! The [`TransactionRequest`][crate::TransactionRequest] is a universal representation for a +//! transaction deserialized from the json input of an RPC call. Depending on what fields are set, +//! it can be converted into the container type [`TypedTransactionRequest`]. use reth_primitives::{AccessList, Address, Bytes, U256}; use reth_rlp::{BufMut, Decodable, DecodeError, Encodable, RlpDecodable, RlpEncodable}; diff --git a/crates/primitives/src/constants.rs b/crates/primitives/src/constants.rs index c73d58c59..d551a9706 100644 --- a/crates/primitives/src/constants.rs +++ b/crates/primitives/src/constants.rs @@ -3,13 +3,13 @@ use crate::H256; use hex_literal::hex; -/// Initial base fee as defined in: https://eips.ethereum.org/EIPS/eip-1559 +/// Initial base fee as defined in [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) pub const EIP1559_INITIAL_BASE_FEE: u64 = 1_000_000_000; -/// Base fee max change denominator as defined in: https://eips.ethereum.org/EIPS/eip-1559 +/// Base fee max change denominator as defined in [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) pub const EIP1559_BASE_FEE_MAX_CHANGE_DENOMINATOR: u64 = 8; -/// Elasticity multiplier as defined in: https://eips.ethereum.org/EIPS/eip-1559 +/// Elasticity multiplier as defined in [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) pub const EIP1559_ELASTICITY_MULTIPLIER: u64 = 2; /// The Ethereum mainnet genesis hash. diff --git a/crates/primitives/src/forkid.rs b/crates/primitives/src/forkid.rs index ed0e1e2c4..bdba0008d 100644 --- a/crates/primitives/src/forkid.rs +++ b/crates/primitives/src/forkid.rs @@ -1,5 +1,6 @@ //! EIP-2124 implementation based on . -//! Previously version of apache licenced: https://crates.io/crates/ethereum-forkid +//! +//! Previously version of Apache licenced [`ethereum-forkid`](https://crates.io/crates/ethereum-forkid). #![deny(missing_docs)] diff --git a/crates/primitives/src/hex_bytes.rs b/crates/primitives/src/hex_bytes.rs index 4512726a5..b7447afa7 100644 --- a/crates/primitives/src/hex_bytes.rs +++ b/crates/primitives/src/hex_bytes.rs @@ -41,7 +41,7 @@ impl LowerHex for Bytes { } impl Bytes { - /// Return bytes as [Vec::] + /// Return bytes as [`Vec::`] pub fn to_vec(&self) -> Vec { self.as_ref().to_vec() } diff --git a/crates/primitives/src/net.rs b/crates/primitives/src/net.rs index ca8360f59..c40490135 100644 --- a/crates/primitives/src/net.rs +++ b/crates/primitives/src/net.rs @@ -14,8 +14,7 @@ use url::{Host, Url}; /// Represents a ENR in discv4. /// -/// Note: this is only an excerpt of the [ENR](enr::Enr) datastructure which is sent in Neighbours -/// message. +/// Note: this is only an excerpt of the [`NodeRecord`] data structure. #[derive( Clone, Copy, diff --git a/crates/stages/src/db.rs b/crates/stages/src/db.rs index 54333fff8..0c248e0b0 100644 --- a/crates/stages/src/db.rs +++ b/crates/stages/src/db.rs @@ -207,7 +207,7 @@ where Ok(()) } - /// Unwind a table forward by a [Walker] on another table + /// Unwind a table forward by a [Walker][reth_db::abstraction::cursor::Walker] on another table pub(crate) fn unwind_table_by_walker(&self, start_at: T1::Key) -> Result<(), Error> where DB: Database, diff --git a/crates/stages/src/error.rs b/crates/stages/src/error.rs index c2e3acb97..e1cf5d912 100644 --- a/crates/stages/src/error.rs +++ b/crates/stages/src/error.rs @@ -41,7 +41,8 @@ pub enum StageError { StageProgress(u64), /// The stage encountered a recoverable error. /// - /// These types of errors are caught by the [Pipeline] and trigger a restart of the stage. + /// These types of errors are caught by the [Pipeline][crate::Pipeline] and trigger a restart + /// of the stage. #[error(transparent)] Recoverable(Box), /// The stage encountered a fatal error. diff --git a/crates/stages/src/pipeline/builder.rs b/crates/stages/src/pipeline/builder.rs index 2f1651317..29362571f 100644 --- a/crates/stages/src/pipeline/builder.rs +++ b/crates/stages/src/pipeline/builder.rs @@ -39,7 +39,7 @@ where /// Stages can be grouped into a set by using a [`StageSet`]. /// /// To customize the stages in the set (reorder, disable, insert a stage) call - /// [`build`][StageSet::build] on the set which will convert it to a + /// [`builder`][StageSet::builder] on the set which will convert it to a /// [`StageSetBuilder`][crate::StageSetBuilder]. pub fn add_stages>(mut self, set: Set) -> Self { for stage in set.builder().build() { diff --git a/crates/stages/src/pipeline/set.rs b/crates/stages/src/pipeline/set.rs index 67e0c35bb..776ddd47d 100644 --- a/crates/stages/src/pipeline/set.rs +++ b/crates/stages/src/pipeline/set.rs @@ -172,7 +172,7 @@ where /// Disables the given stage. /// /// The disabled [`Stage`] keeps its place in the set, so it can be used for ordering with - /// [`add_before`] or [`add_after`], or it can be re-enabled. + /// [`StageSetBuilder::add_before`] or [`StageSetBuilder::add_after`], or it can be re-enabled. /// /// All stages within a [`StageSet`] are enabled by default. /// diff --git a/crates/stages/src/stages/bodies.rs b/crates/stages/src/stages/bodies.rs index 12a395e88..ccd50c8fd 100644 --- a/crates/stages/src/stages/bodies.rs +++ b/crates/stages/src/stages/bodies.rs @@ -38,17 +38,22 @@ pub const BODIES: StageId = StageId("Bodies"); /// /// The bodies are processed and data is inserted into these tables: /// -/// - [`BlockOmmers`][reth_interfaces::db::tables::BlockOmmers] -/// - [`Transactions`][reth_interfaces::db::tables::Transactions] +/// - [`BlockOmmers`][reth_db::tables::BlockOmmers] +/// - [`BlockBodies`][reth_db::tables::BlockBodies] +/// - [`Transactions`][reth_db::tables::Transactions] +/// - [`BlockTransitionIndex`][reth_db::tables::BlockTransitionIndex] +/// - [`TxTransitionIndex`][reth_db::tables::TxTransitionIndex] /// /// # Genesis /// /// This stage expects that the genesis has been inserted into the appropriate tables: /// -/// - The header tables (see [`HeaderStage`][crate::stages::headers::HeaderStage]) -/// - The [`BlockOmmers`][reth_interfaces::db::tables::BlockOmmers] table -/// - The [`CumulativeTxCount`][reth_interfaces::db::tables::CumulativeTxCount] table -/// - The [`Transactions`][reth_interfaces::db::tables::Transactions] table +/// - The header tables (see [`HeaderStage`][crate::stages::HeaderStage]) +/// - The [`BlockOmmers`][reth_db::tables::BlockOmmers] table +/// - The [`BlockBodies`][reth_db::tables::BlockBodies] table +/// - The [`Transactions`][reth_db::tables::Transactions] table +/// - The [`BlockTransitionIndex`][reth_db::tables::BlockTransitionIndex] table +/// - The [`TxTransitionIndex`][reth_db::tables::TxTransitionIndex] table #[derive(Debug)] pub struct BodyStage { /// The body downloader. diff --git a/crates/stages/src/stages/execution.rs b/crates/stages/src/stages/execution.rs index 8aaec4dde..48ad2f0b1 100644 --- a/crates/stages/src/stages/execution.rs +++ b/crates/stages/src/stages/execution.rs @@ -27,28 +27,28 @@ pub const EXECUTION: StageId = StageId("Execution"); /// update history indexes. /// /// Input tables: -/// [tables::CanonicalHeaders] get next block to execute. -/// [tables::Headers] get for revm environment variables. -/// [tables::CumulativeTxCount] to get tx number -/// [tables::Transactions] to execute +/// - [tables::CanonicalHeaders] get next block to execute. +/// - [tables::Headers] get for revm environment variables. +/// - [tables::BlockBodies] to get tx number +/// - [tables::Transactions] to execute /// -/// For state access [StateProvider] provides us latest state and history state -/// For latest most recent state [StateProvider] would need (Used for execution Stage): -/// [tables::PlainAccountState] -/// [tables::Bytecodes] -/// [tables::PlainStorageState] +/// For state access [LatestStateProviderRef] provides us latest state and history state +/// For latest most recent state [LatestStateProviderRef] would need (Used for execution Stage): +/// - [tables::PlainAccountState] +/// - [tables::Bytecodes] +/// - [tables::PlainStorageState] /// /// Tables updated after state finishes execution: -/// [tables::PlainAccountState] -/// [tables::PlainStorageState] -/// [tables::Bytecodes] -/// [tables::AccountChangeSet] -/// [tables::StorageChangeSet] +/// - [tables::PlainAccountState] +/// - [tables::PlainStorageState] +/// - [tables::Bytecodes] +/// - [tables::AccountChangeSet] +/// - [tables::StorageChangeSet] /// /// For unwinds we are accessing: -/// [tables::CumulativeTxCount] get tx index to know what needs to be unwinded -/// [tables::AccountHistory] to remove change set and apply old values to -/// [tables::PlainAccountState] [tables::StorageHistory] to remove change set and apply old values +/// - [tables::BlockBodies] get tx index to know what needs to be unwinded +/// - [tables::AccountHistory] to remove change set and apply old values to +/// - [tables::PlainAccountState] [tables::StorageHistory] to remove change set and apply old values /// to [tables::PlainStorageState] #[derive(Debug)] pub struct ExecutionStage { diff --git a/crates/stages/src/stages/headers.rs b/crates/stages/src/stages/headers.rs index be13bedd6..cc9e2006c 100644 --- a/crates/stages/src/stages/headers.rs +++ b/crates/stages/src/stages/headers.rs @@ -28,9 +28,9 @@ pub const HEADERS: StageId = StageId("Headers"); /// /// The headers are processed and data is inserted into these tables: /// -/// - [`HeaderNumbers`][reth_interfaces::db::tables::HeaderNumbers] -/// - [`Headers`][reth_interfaces::db::tables::Headers] -/// - [`CanonicalHeaders`][reth_interfaces::db::tables::CanonicalHeaders] +/// - [`HeaderNumbers`][reth_db::tables::HeaderNumbers] +/// - [`Headers`][reth_db::tables::Headers] +/// - [`CanonicalHeaders`][reth_db::tables::CanonicalHeaders] /// /// NOTE: This stage downloads headers in reverse. Upon returning the control flow to the pipeline, /// the stage progress is not updated unless this stage is done. diff --git a/crates/stages/src/stages/sender_recovery.rs b/crates/stages/src/stages/sender_recovery.rs index 26563072e..c49bc853d 100644 --- a/crates/stages/src/stages/sender_recovery.rs +++ b/crates/stages/src/stages/sender_recovery.rs @@ -20,7 +20,7 @@ const SENDER_RECOVERY: StageId = StageId("SenderRecovery"); /// The sender recovery stage iterates over existing transactions, /// recovers the transaction signer and stores them -/// in [`TxSenders`][reth_interfaces::db::tables::TxSenders] table. +/// in [`TxSenders`][reth_db::tables::TxSenders] table. #[derive(Debug)] pub struct SenderRecoveryStage { /// The size of the chunk for parallel sender recovery @@ -57,10 +57,10 @@ impl Stage for SenderRecoveryStage { } /// Retrieve the range of transactions to iterate over by querying - /// [`CumulativeTxCount`][reth_interfaces::db::tables::CumulativeTxCount], + /// [`BlockBodies`][reth_db::tables::BlockBodies], /// collect transactions within that range, /// recover signer for each transaction and store entries in - /// the [`TxSenders`][reth_interfaces::db::tables::TxSenders] table. + /// the [`TxSenders`][reth_db::tables::TxSenders] table. async fn execute( &mut self, tx: &mut Transaction<'_, DB>, diff --git a/crates/stages/src/stages/total_difficulty.rs b/crates/stages/src/stages/total_difficulty.rs index 83dbda193..9edf5e1b9 100644 --- a/crates/stages/src/stages/total_difficulty.rs +++ b/crates/stages/src/stages/total_difficulty.rs @@ -16,7 +16,7 @@ const TOTAL_DIFFICULTY: StageId = StageId("TotalDifficulty"); /// The total difficulty stage. /// /// This stage walks over inserted headers and computes total difficulty -/// at each block. The entries are inserted into [`HeaderTD`][reth_interfaces::db::tables::HeaderTD] +/// at each block. The entries are inserted into [`HeaderTD`][reth_db::tables::HeaderTD] /// table. #[derive(Debug)] pub struct TotalDifficultyStage { diff --git a/crates/storage/codecs/derive/src/compact/generator.rs b/crates/storage/codecs/derive/src/compact/generator.rs index cc65ea161..dcc71924d 100644 --- a/crates/storage/codecs/derive/src/compact/generator.rs +++ b/crates/storage/codecs/derive/src/compact/generator.rs @@ -1,8 +1,8 @@ -//! Code generator for the [`Compact`] trait. +//! Code generator for the `Compact` trait. use super::*; -/// Generates code to implement the [`Compact`] trait for a data type. +/// Generates code to implement the `Compact` trait for a data type. pub fn generate_from_to(ident: &Ident, fields: &FieldList) -> TokenStream2 { let flags = format_ident!("{ident}Flags"); @@ -47,7 +47,7 @@ pub fn generate_from_to(ident: &Ident, fields: &FieldList) -> TokenStream2 { } } -/// Generates code to implement the [`Compact`] trait method `to_compact`. +/// Generates code to implement the `Compact` trait method `to_compact`. fn generate_from_compact(fields: &FieldList, ident: &Ident) -> Vec { let mut lines = vec![]; let mut known_types = vec!["H256", "H160", "Address", "Bloom", "Vec"]; @@ -102,7 +102,7 @@ fn generate_from_compact(fields: &FieldList, ident: &Ident) -> Vec lines } -/// Generates code to implement the [`Compact`] trait method `from_compact`. +/// Generates code to implement the `Compact` trait method `from_compact`. fn generate_to_compact(fields: &FieldList, ident: &Ident) -> Vec { let mut lines = vec![quote! { let mut buffer = bytes::BytesMut::new(); diff --git a/crates/storage/codecs/derive/src/compact/mod.rs b/crates/storage/codecs/derive/src/compact/mod.rs index 7a07c881e..4cc254a95 100644 --- a/crates/storage/codecs/derive/src/compact/mod.rs +++ b/crates/storage/codecs/derive/src/compact/mod.rs @@ -40,7 +40,7 @@ pub enum FieldTypes { EnumUnnamedField((FieldType, UseAlternative)), } -/// Derives the [`Compact`] trait and its from/to implementations. +/// Derives the `Compact` trait and its from/to implementations. pub fn derive(input: TokenStream) -> TokenStream { let mut output = quote! {}; @@ -134,8 +134,9 @@ fn load_field(field: &syn::Field, fields: &mut FieldList, is_enum: bool) { } /// Since there's no impl specialization in rust stable atm, once we find we have a -/// Vec/Option we try to find out if it's a Vec/Option of a fixed size data type. -/// eg, Vec. If so, we use another impl to code/decode its data. +/// Vec/Option we try to find out if it's a Vec/Option of a fixed size data type, e.g. `Vec`. +/// +/// If so, we use another impl to code/decode its data. fn should_use_alt_impl(ftype: &String, segment: &syn::PathSegment) -> bool { if *ftype == "Vec" || *ftype == "Option" { if let syn::PathArguments::AngleBracketed(ref args) = segment.arguments { diff --git a/crates/storage/codecs/derive/src/lib.rs b/crates/storage/codecs/derive/src/lib.rs index 0588bea5a..8d65bc019 100644 --- a/crates/storage/codecs/derive/src/lib.rs +++ b/crates/storage/codecs/derive/src/lib.rs @@ -134,7 +134,7 @@ pub fn derive_arbitrary(args: TokenStream, input: TokenStream) -> TokenStream { .into() } -/// To be used for types that implement `Arbitrary` manually. See [`derive_arbitrary`] for more. +/// To be used for types that implement `Arbitrary` manually. See [`derive_arbitrary()`] for more. #[proc_macro_attribute] pub fn add_arbitrary_tests(args: TokenStream, input: TokenStream) -> TokenStream { let ast = parse_macro_input!(input as DeriveInput); diff --git a/crates/storage/codecs/src/lib.rs b/crates/storage/codecs/src/lib.rs index d54947546..72203f3a1 100644 --- a/crates/storage/codecs/src/lib.rs +++ b/crates/storage/codecs/src/lib.rs @@ -17,8 +17,8 @@ use revm_interpreter::{B160 as H160, B256 as H256, U256}; /// add their definitions to `get_bit_size()` or `known_types` in `generator.rs`. /// /// Regarding the `specialized_to/from_compact` methods: Mainly used as a workaround for not being -/// able to specialize an impl over certain types like Vec/Option where T is a fixed size -/// array like Vec. +/// able to specialize an impl over certain types like `Vec`/`Option` where `T` is a fixed +/// size array like `Vec`. pub trait Compact { /// Takes a buffer which can be written to. *Ideally*, it returns the length written to. fn to_compact(self, buf: &mut impl bytes::BufMut) -> usize; @@ -113,7 +113,7 @@ where (list, buf) } - /// To be used by fixed sized types like Vec. + /// To be used by fixed sized types like `Vec`. fn specialized_to_compact(self, buf: &mut impl bytes::BufMut) -> usize { buf.put_u16(self.len() as u16); @@ -123,7 +123,7 @@ where 0 } - /// To be used by fixed sized types like Vec. + /// To be used by fixed sized types like `Vec`. fn specialized_from_compact(mut buf: &[u8], len: usize) -> (Self, &[u8]) { let mut list = vec![]; let length = buf.get_u16(); @@ -169,7 +169,7 @@ where (Some(element), buf) } - /// To be used by fixed sized types like Option. + /// To be used by fixed sized types like `Option`. fn specialized_to_compact(self, buf: &mut impl bytes::BufMut) -> usize { if let Some(element) = self { element.to_compact(buf); @@ -178,7 +178,7 @@ where 0 } - /// To be used by fixed sized types like Option. + /// To be used by fixed sized types like `Option`. fn specialized_from_compact(buf: &[u8], len: usize) -> (Self, &[u8]) { if len == 0 { return (None, buf) diff --git a/crates/storage/db/src/abstraction/cursor.rs b/crates/storage/db/src/abstraction/cursor.rs index dea015a3a..71fb15ff3 100644 --- a/crates/storage/db/src/abstraction/cursor.rs +++ b/crates/storage/db/src/abstraction/cursor.rs @@ -86,7 +86,8 @@ pub trait DbCursorRW<'tx, T: Table> { /// Append value to next cursor item. /// - /// This is efficient for pre-sorted data. If the data is not pre-sorted, use [`insert`]. + /// This is efficient for pre-sorted data. If the data is not pre-sorted, use + /// [`DbCursorRW::insert`]. fn append(&mut self, key: T::Key, value: T::Value) -> Result<(), Error>; /// Delete current value that cursor points to @@ -100,7 +101,7 @@ pub trait DbDupCursorRW<'tx, T: DupSort> { /// Append duplicate value. /// - /// This is efficient for pre-sorted data. If the data is not pre-sorted, use [`insert`]. + /// This is efficient for pre-sorted data. If the data is not pre-sorted, use `insert`. fn append_dup(&mut self, key: T::Key, value: T::Value) -> Result<(), Error>; } diff --git a/crates/storage/db/src/abstraction/database.rs b/crates/storage/db/src/abstraction/database.rs index 5e47bc456..7aff2d400 100644 --- a/crates/storage/db/src/abstraction/database.rs +++ b/crates/storage/db/src/abstraction/database.rs @@ -5,7 +5,7 @@ use crate::{ }; /// Implements the GAT method from: -/// https://sabrinajewson.org/blog/the-better-alternative-to-lifetime-gats#the-better-gats. +/// . /// /// Sealed trait which cannot be implemented by 3rd parties, exposed only for implementers pub trait DatabaseGAT<'a, __ImplicitBounds: Sealed = Bounds<&'a Self>>: Send + Sync { diff --git a/crates/storage/db/src/abstraction/table.rs b/crates/storage/db/src/abstraction/table.rs index 851d4e42b..fb1583a47 100644 --- a/crates/storage/db/src/abstraction/table.rs +++ b/crates/storage/db/src/abstraction/table.rs @@ -48,12 +48,12 @@ impl Value for T where T: Compress + Decompress + Serialize {} /// Generic trait that a database table should follow. /// -/// [`Table::Key`], [`Table::Value`], [`Table::SeekKey`] types should implement [`Encode`] and +/// The [`Table::Key`] and [`Table::Value`] types should implement [`Encode`] and /// [`Decode`] when appropriate. These traits define how the data is stored and read from the /// database. /// -/// It allows for the use of codecs. See [`crate::kv::models::blocks::BlockNumHash`] for a custom -/// implementation, and [`crate::kv::codecs::scale`] for the use of an external codec. +/// It allows for the use of codecs. See [`crate::models::BlockNumHash`] for a custom +/// implementation. pub trait Table: Send + Sync + Debug + 'static { /// Return table name as it is present inside the MDBX. const NAME: &'static str; @@ -65,11 +65,14 @@ pub trait Table: Send + Sync + Debug + 'static { type Value: Value; } -/// DupSort allows for keys not to be repeated in the database, -/// for more check: https://libmdbx.dqdkfa.ru/usage.html#autotoc_md48 +/// DupSort allows for keys to be repeated in the database. +/// +/// Upstream docs: pub trait DupSort: Table { - /// Subkey type. For more check https://libmdbx.dqdkfa.ru/usage.html#autotoc_md48 + /// The table subkey. This type must implement [`Encode`] and [`Decode`]. /// /// Sorting should be taken into account when encoding this. + /// + /// Upstream docs: type SubKey: Key; } diff --git a/crates/storage/db/src/abstraction/transaction.rs b/crates/storage/db/src/abstraction/transaction.rs index 3c3e1a1b1..81798cb08 100644 --- a/crates/storage/db/src/abstraction/transaction.rs +++ b/crates/storage/db/src/abstraction/transaction.rs @@ -6,7 +6,7 @@ use crate::{ }; /// Implements the GAT method from: -/// https://sabrinajewson.org/blog/the-better-alternative-to-lifetime-gats#the-better-gats. +/// . /// /// Sealed trait which cannot be implemented by 3rd parties, exposed only for implementers pub trait DbTxGAT<'a, __ImplicitBounds: Sealed = Bounds<&'a Self>>: Send + Sync { @@ -17,7 +17,7 @@ pub trait DbTxGAT<'a, __ImplicitBounds: Sealed = Bounds<&'a Self>>: Send + Sync } /// Implements the GAT method from: -/// https://sabrinajewson.org/blog/the-better-alternative-to-lifetime-gats#the-better-gats. +/// . /// /// Sealed trait which cannot be implemented by 3rd parties, exposed only for implementers pub trait DbTxMutGAT<'a, __ImplicitBounds: Sealed = Bounds<&'a Self>>: Send + Sync { diff --git a/crates/storage/db/src/tables/codecs/fuzz/mod.rs b/crates/storage/db/src/tables/codecs/fuzz/mod.rs index 78e1b04c5..4fa443e0b 100644 --- a/crates/storage/db/src/tables/codecs/fuzz/mod.rs +++ b/crates/storage/db/src/tables/codecs/fuzz/mod.rs @@ -77,7 +77,7 @@ macro_rules! impl_fuzzer_value { /// Fuzzer generates a random instance of the object and proceeds to compress and decompress it. It /// then makes sure that it matches the original object. It supports being fed a different kind of -/// input, as long as it supports Into. +/// input, as long as it supports `Into`. macro_rules! impl_fuzzer_value_with_input { ($(($name:tt, $input:tt)),+) => { $( diff --git a/crates/storage/db/src/tables/models/accounts.rs b/crates/storage/db/src/tables/models/accounts.rs index 3c9a1c18e..4ca5a7351 100644 --- a/crates/storage/db/src/tables/models/accounts.rs +++ b/crates/storage/db/src/tables/models/accounts.rs @@ -10,7 +10,9 @@ use reth_codecs::Compact; use reth_primitives::{Account, Address, TransitionId}; use serde::{Deserialize, Serialize}; -/// Account as it is saved inside [`AccountChangeSet`]. [`Address`] is the subkey. +/// Account as it is saved inside [`AccountChangeSet`][crate::tables::AccountChangeSet]. +/// +/// [`Address`] is the subkey. #[derive(Debug, Default, Clone, Eq, PartialEq, Serialize)] pub struct AccountBeforeTx { /// Address for the account. Acts as `DupSort::SubKey`. @@ -39,7 +41,8 @@ impl Compact for AccountBeforeTx { } } -/// [`TxNumber`] concatenated with [`Address`]. Used as a key for [`StorageChangeSet`] +/// [`TransitionId`] concatenated with [`Address`]. Used as the key for +/// [`StorageChangeSet`](crate::tables::StorageChangeSet) /// /// Since it's used as a key, it isn't compressed when encoding it. #[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, Ord, PartialOrd)] @@ -56,7 +59,7 @@ impl TransitionIdAddress { self.0 .1 } - /// Consumes `Self` and returns [`TxNumber`], [`Address`] + /// Consumes `Self` and returns [`TransitionId`], [`Address`] pub fn take(self) -> (TransitionId, Address) { (self.0 .0, self.0 .1) } diff --git a/crates/storage/db/src/tables/models/blocks.rs b/crates/storage/db/src/tables/models/blocks.rs index 3433249d8..4fd92fda1 100644 --- a/crates/storage/db/src/tables/models/blocks.rs +++ b/crates/storage/db/src/tables/models/blocks.rs @@ -12,7 +12,7 @@ use reth_codecs::{main_codec, Compact}; use reth_primitives::{BlockHash, BlockNumber, Header, TxNumber, H256}; use serde::{Deserialize, Serialize}; -/// Total chain number of transactions. Value for [`CumulativeTxCount`]. // TODO: +/// Total number of transactions. pub type NumTransactions = u64; /// The storage representation of a block. @@ -58,7 +58,7 @@ pub struct StoredBlockOmmers { pub ommers: Vec
, } -/// Hash of the block header. Value for [`CanonicalHeaders`] +/// Hash of the block header. Value for [`CanonicalHeaders`][crate::tables::CanonicalHeaders] pub type HeaderHash = H256; /// BlockNumber concatenated with BlockHash. Used as a key for multiple tables. Having the first diff --git a/crates/storage/db/src/tables/utils.rs b/crates/storage/db/src/tables/utils.rs index 198356507..8cd68d88e 100644 --- a/crates/storage/db/src/tables/utils.rs +++ b/crates/storage/db/src/tables/utils.rs @@ -7,7 +7,8 @@ use bytes::Bytes; use std::borrow::Cow; #[macro_export] -/// Implements the [`arbitrary::Arbitrary`] trait for types with fixed array types. +/// Implements the `Arbitrary` trait for types with fixed array +/// types. macro_rules! impl_fixed_arbitrary { ($name:tt, $size:tt) => { #[cfg(any(test, feature = "arbitrary"))] diff --git a/crates/storage/libmdbx-rs/README.md b/crates/storage/libmdbx-rs/README.md index 16436ddad..0ead0242b 100644 --- a/crates/storage/libmdbx-rs/README.md +++ b/crates/storage/libmdbx-rs/README.md @@ -4,7 +4,7 @@ Rust bindings for [libmdbx](https://libmdbx.dqdkfa.ru). Forked from an earlier Apache licenced version of the `libmdbx-rs` crate, before it changed licence to GPL. -NOTE: Most of the repo came from lmdb-rs bindings: https://github.com/mozilla/lmdb-rs. +NOTE: Most of the repo came from [lmdb-rs bindings](https://github.com/mozilla/lmdb-rs). ## Updating the libmdbx Version diff --git a/crates/storage/provider/src/utils.rs b/crates/storage/provider/src/utils.rs index 166688c10..341ab4e8b 100644 --- a/crates/storage/provider/src/utils.rs +++ b/crates/storage/provider/src/utils.rs @@ -9,10 +9,10 @@ use reth_primitives::SealedBlock; /// Insert block data into corresponding tables. Used mainly for testing & internal tooling. /// /// -/// Check parent dependency in [tables::HeaderNumbers] and in [tables::CumulativeTxCount] tables. +/// Check parent dependency in [tables::HeaderNumbers] and in [tables::BlockBodies] tables. /// Inserts blocks data to [tables::CanonicalHeaders], [tables::Headers], [tables::HeaderNumbers], /// and transactions data to [tables::TxSenders], [tables::Transactions], -/// [tables::CumulativeTxCount] and [tables::BlockBodies] +/// [tables::BlockBodies] and [tables::BlockBodies] pub fn insert_block<'a, TX: DbTxMut<'a> + DbTx<'a>>( tx: &TX, block: &SealedBlock, diff --git a/crates/transaction-pool/src/pool/best.rs b/crates/transaction-pool/src/pool/best.rs index 1b315bd78..078e68a58 100644 --- a/crates/transaction-pool/src/pool/best.rs +++ b/crates/transaction-pool/src/pool/best.rs @@ -13,10 +13,10 @@ use tracing::debug; /// An iterator that returns transactions that can be executed on the current state (*best* /// transactions). /// -/// The [`PendingPool`] contains transactions that *could* all be executed on the current state, but -/// only yields transactions that are ready to be executed now. -/// While it contains all gapless transactions of a sender, it _always_ only returns the transaction -/// with the current on chain nonce. +/// The [`PendingPool`](crate::pool::pending::PendingPool) contains transactions that *could* all +/// be executed on the current state, but only yields transactions that are ready to be executed +/// now. While it contains all gapless transactions of a sender, it _always_ only returns the +/// transaction with the current on chain nonce. pub(crate) struct BestTransactions { /// Contains a copy of _all_ transactions of the pending pool at the point in time this /// iterator was created. diff --git a/crates/transaction-pool/src/pool/mod.rs b/crates/transaction-pool/src/pool/mod.rs index 3b7cc0deb..8ebdacb6a 100644 --- a/crates/transaction-pool/src/pool/mod.rs +++ b/crates/transaction-pool/src/pool/mod.rs @@ -89,7 +89,7 @@ mod best; mod events; mod listener; mod parked; -mod pending; +pub(crate) mod pending; pub(crate) mod size; pub(crate) mod state; mod transaction; @@ -472,7 +472,7 @@ impl AddedTransaction { } } -/// Contains all state changes after a [`NewBlockEvent`] was processed +/// Contains all state changes after a [`OnNewBlockEvent`] was processed #[derive(Debug)] pub(crate) struct OnNewBlockOutcome { /// Hash of the block. diff --git a/crates/transaction-pool/src/pool/pending.rs b/crates/transaction-pool/src/pool/pending.rs index 5e65feb95..e5751c687 100644 --- a/crates/transaction-pool/src/pool/pending.rs +++ b/crates/transaction-pool/src/pool/pending.rs @@ -38,7 +38,7 @@ pub(crate) struct PendingPool { independent_transactions: BTreeSet>, /// Keeps track of the size of this pool. /// - /// See also [`PoolTransaction::size`]. + /// See also [`PoolTransaction::size`](crate::traits::PoolTransaction::size). size_of: SizeTracker, } diff --git a/crates/transaction-pool/src/pool/txpool.rs b/crates/transaction-pool/src/pool/txpool.rs index 5bfe5993c..2ec46d394 100644 --- a/crates/transaction-pool/src/pool/txpool.rs +++ b/crates/transaction-pool/src/pool/txpool.rs @@ -28,7 +28,7 @@ use std::{ /// The minimal value the basefee can decrease to /// -/// The `BASE_FEE_MAX_CHANGE_DENOMINATOR` (https://eips.ethereum.org/EIPS/eip-1559) is `8`, or 12.5%, once the base fee has dropped to `7` WEI it cannot decrease further because 12.5% of 7 is less than 1. +/// The `BASE_FEE_MAX_CHANGE_DENOMINATOR` is `8`, or 12.5%, once the base fee has dropped to `7` WEI it cannot decrease further because 12.5% of 7 is less than 1. pub(crate) const MIN_PROTOCOL_BASE_FEE: u128 = 7; /// A pool that manages transactions.