ci: ensure docs build (#1073)

Co-authored-by: xqft <estefano.bargas@fing.edu.uy>
Co-authored-by: lambdaclass-user <github@lambdaclass.com>

.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

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<T: Table>(&mut self, start: usize, len: usize) -> Result<BTreeMap<T::Key, T::Value>> {
         let data = self.db.view(|tx| {
             let mut cursor = tx.cursor_read::<T>().expect("Was not able to obtain a cursor.");

crate-template/src/lib.rs

@@ -5,4 +5,4 @@
     attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
 ))]
 
-//! <reth crate template>
+//! reth crate template

crates/consensus/src/engine/error.rs

@@ -4,7 +4,7 @@ use thiserror::Error;
 /// The Engine API result type
 pub type EngineApiResult<Ok> = Result<Ok, EngineApiError>;
 
-/// Error returned by [`EngineApi`][crate::engine::EngineApi]
+/// Error returned by [`EthConsensusEngine`][crate::engine::EthConsensusEngine]
 #[derive(Error, Debug)]
 pub enum EngineApiError {
     /// Invalid payload extra data.

crates/consensus/src/engine/mod.rs

@@ -112,7 +112,8 @@ impl<Client: HeaderProvider + BlockProvider + StateProvider> 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 <https://github.com/ethereum/go-ethereum/blob/79a478bb6176425c2400e949890e668a3d9a3d05/core/beacon/types.go#L145>
     fn try_construct_block(&self, payload: ExecutionPayload) -> EngineApiResult<SealedBlock> {
         if payload.extra_data.len() > 32 {
             return Err(EngineApiError::PayloadExtraData(payload.extra_data))

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};
 

crates/interfaces/src/consensus.rs

@@ -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;
 }
 

crates/interfaces/src/p2p/bodies/downloader.rs

@@ -10,7 +10,8 @@ pub type BodyDownloaderResult = DownloadResult<Vec<BlockResponse>>;
 /// 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<Item = BodyDownloaderResult> + Unpin {
     /// Method for setting the download range.
     fn set_download_range(&mut self, range: Range<BlockNumber>) -> DownloadResult<()>;

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<T> = Result<T, RequestError>;
 
-/// Result with [PeerId]
+/// Result with [PeerId][reth_primitives::PeerId]
 pub type PeerRequestResult<T> = RequestResult<WithPeerId<T>>;
 
 /// Helper trait used to validate responses.

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<Item = Vec<SealedHeader>> + Unpin {

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

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 {

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 <https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels>
 static METRIC_NAME_RE: Lazy<Regex> =
     Lazy::new(|| Regex::new(r"^[a-zA-Z_:.][a-zA-Z0-9_:.]*$").unwrap());
 
@@ -27,7 +28,8 @@ pub(crate) fn derive(node: &DeriveInput) -> Result<proc_macro2::TokenStream> {
     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 <https://docs.rs/metrics/0.20.1/metrics/index.html#macros>
     };
     let register_and_describe = match &metrics_attr.scope {
         MetricsScope::Static(scope) => {

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 <https://github.com/libp2p/rust-libp2p/blob/master/src/bandwidth.rs>
 
 // Copyright 2019 Parity Technologies (UK) Ltd.
 //

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
+//! <https://github.com/sigp/discv5>
 
 use bytes::{Bytes, BytesMut};
 use reth_net_common::ban_list::BanList;

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.

crates/net/dns/src/error.rs

@@ -5,7 +5,7 @@ pub(crate) type ParseEntryResult<T> = Result<T, ParseDnsEntryError>;
 
 pub(crate) type LookupResult<T> = Result<T, LookupError>;
 
-/// Error while parsing a [DnsEntry]
+/// Error while parsing a [DnsEntry](crate::tree::DnsEntry)
 #[derive(thiserror::Error, Debug)]
 #[allow(missing_docs)]
 pub enum ParseDnsEntryError {

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

crates/net/downloaders/src/bodies/request.rs

@@ -26,9 +26,9 @@ type BodiesFut = Pin<Box<dyn Future<Output = PeerRequestResult<Vec<BlockBody>>>
 /// 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

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

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
     }

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.

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};

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,
 }
 

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.

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(),

crates/net/ipc/src/server/mod.rs

@@ -217,7 +217,7 @@ pub(crate) struct ServiceData<L: Logger> {
 /// 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<L: Logger> {
     inner: ServiceData<L>,
@@ -430,8 +430,7 @@ impl<B, L> Builder<B, L> {
     /// 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,

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;
 

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`

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 {

crates/net/network/src/manager.rs

@@ -130,7 +130,7 @@ impl<C> NetworkManager<C> {
         &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()

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 {

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<AtomicUsize>,
-    /// Sender half of the message channel to the [`NetworkManager`].
+    /// Sender half of the message channel to the [`crate::NetworkManager`].
     to_manager_tx: UnboundedSender<NetworkHandleMessage>,
     /// The local address that accepts incoming connections.
     listener_address: Arc<Mutex<SocketAddr>>,

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<PeerAction> {
         loop {
             // drain buffered actions

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<SessionCommand>,
-    /// Sink to send messages to the [`SessionManager`].
+    /// Sink to send messages to the [`SessionManager`](super::SessionManager).
     pub(crate) to_session: mpsc::Sender<ActiveSessionMessage>,
     /// Incoming request to send to delegate to the remote peer.
     pub(crate) request_tx: Fuse<ReceiverStream<PeerRequest>>,
@@ -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,

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

@@ -83,12 +83,12 @@ pub(crate) struct SessionManager {
     pending_sessions_tx: mpsc::Sender<PendingSessionEvent>,
     /// Receiver half that listens for [`PendingSessionEvent`] produced by pending sessions.
     pending_session_rx: ReceiverStream<PendingSessionEvent>,
-    /// 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<ActiveSessionMessage>,
-    /// Receiver half that listens for [`ActiveSessionEvent`] produced by pending sessions.
+    /// Receiver half that listens for [`ActiveSessionMessage`] produced by pending sessions.
     active_session_rx: ReceiverStream<ActiveSessionMessage>,
     /// 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<F>(&self, f: F)
     where
         F: Future<Output = ()> + Send + 'static,

crates/net/network/src/state.rs

@@ -465,7 +465,7 @@ pub(crate) struct ActivePeer {
     pub(crate) blocks: LruCache<H256>,
 }
 
-/// Message variants triggered by the [`State`]
+/// Message variants triggered by the [`NetworkState`]
 pub(crate) enum StateAction {
     /// Dispatch a `NewBlock` message to the peer
     NewBlock {

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<Option<Self::Item>> {
         let this = self.get_mut();

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<PeerId> {
         let peer_id = match self.inner.next().await {
             Some(NetworkEvent::PeerAdded(peer_id)) => peer_id,

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),
 }

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: <https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-admin>
 #[derive(Serialize, Deserialize, Debug)]
 pub struct NodeInfo {
     /// Enode in URL format.

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 <https://openethereum.github.io/JSONRPC-trace-module>
 
 use reth_primitives::{Address, Bytes, H256, U256, U64};
 use serde::{Deserialize, Serialize};

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};

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.

crates/primitives/src/forkid.rs

@@ -1,5 +1,6 @@
 //! EIP-2124 implementation based on <https://eips.ethereum.org/EIPS/eip-2124>.
-//! 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)]
 

crates/primitives/src/hex_bytes.rs

@@ -41,7 +41,7 @@ impl LowerHex for Bytes {
 }
 
 impl Bytes {
-    /// Return bytes as [Vec::<u8>]
+    /// Return bytes as [`Vec::<u8>`]
     pub fn to_vec(&self) -> Vec<u8> {
         self.as_ref().to_vec()
     }

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,

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<T1, T2>(&self, start_at: T1::Key) -> Result<(), Error>
     where
         DB: Database,

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<dyn std::error::Error + Send + Sync>),
     /// The stage encountered a fatal error.

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<Set: StageSet<DB>>(mut self, set: Set) -> Self {
         for stage in set.builder().build() {

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.
     ///

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<D: BodyDownloader> {
     /// The body downloader.

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 {

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.

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<DB: Database> Stage<DB> 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>,

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 {

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<TokenStream2> {
     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<TokenStream2>
     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<TokenStream2> {
     let mut lines = vec![quote! {
         let mut buffer = bytes::BytesMut::new();

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<H256>. 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<H256>`.
+///
+/// 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 {

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);

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<T>/Option<T> where T is a fixed size
-/// array like Vec<H256>.
+/// able to specialize an impl over certain types like `Vec<T>`/`Option<T>` where `T` is a fixed
+/// size array like `Vec<H256>`.
 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<H256>.
+    /// To be used by fixed sized types like `Vec<H256>`.
     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<H256>.
+    /// To be used by fixed sized types like `Vec<H256>`.
     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<H256>.
+    /// To be used by fixed sized types like `Option<H256>`.
     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<H256>.
+    /// To be used by fixed sized types like `Option<H256>`.
     fn specialized_from_compact(buf: &[u8], len: usize) -> (Self, &[u8]) {
         if len == 0 {
             return (None, buf)

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>;
 }
 

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.
+/// <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 {

crates/storage/db/src/abstraction/table.rs

@@ -48,12 +48,12 @@ impl<T> 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: <https://libmdbx.dqdkfa.ru/usage.html#autotoc_md48>
 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: <https://libmdbx.dqdkfa.ru/usage.html#autotoc_md48>
     type SubKey: Key;
 }

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.
+/// <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.
+/// <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 {

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<T>.
+/// input, as long as it supports `Into<T>`.
 macro_rules! impl_fuzzer_value_with_input {
     ($(($name:tt, $input:tt)),+) => {
         $(

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)
     }

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<Header>,
 }
 
-/// 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

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"))]

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
 

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,

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<T: TransactionOrdering> {
     /// Contains a copy of _all_ transactions of the pending pool at the point in time this
     /// iterator was created.

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<T: PoolTransaction> AddedTransaction<T> {
     }
 }
 
-/// 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.

crates/transaction-pool/src/pool/pending.rs

@@ -38,7 +38,7 @@ pub(crate) struct PendingPool<T: TransactionOrdering> {
     independent_transactions: BTreeSet<PendingTransactionRef<T>>,
     /// Keeps track of the size of this pool.
     ///
-    /// See also [`PoolTransaction::size`].
+    /// See also [`PoolTransaction::size`](crate::traits::PoolTransaction::size).
     size_of: SizeTracker,
 }
 

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` <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.
 pub(crate) const MIN_PROTOCOL_BASE_FEE: u128 = 7;
 
 /// A pool that manages transactions.