ci: ensure docs build (paradigmxyz#1073)

Co-authored-by: xqft <[email protected]>
Co-authored-by: lambdaclass-user <[email protected]>

.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

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

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