docs: fix rustdoc diagnostics and guard them in CI

.github/workflows/ci.yml

@@ -34,6 +34,25 @@ jobs:
       - name: Run cargo fmt
         run: cargo fmt --all -- --check
 
+  rust-docs:
+    name: Rust Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends libclang-dev zlib1g-dev
+
+      - name: Install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          cache-shared-key: rust-docs
+
+      - name: Build docs
+        run: cargo doc --workspace --no-deps --all-features --locked
+        env:
+          RUSTDOCFLAGS: -D warnings
+
   rust-deps:
     name: Rust Dependencies
     runs-on: ubuntu-latest

crates/engine-bench/src/cli.rs

@@ -51,7 +51,7 @@ pub struct CommonArgs {
     /// Timeout for Ethereum JSON-RPC requests used by this command, in milliseconds (must be >= 1).
     #[arg(long, value_name = "MILLISECONDS", default_value_t = 10_000, value_parser = clap::value_parser!(u64).range(1..))]
     pub eth_rpc_timeout_ms: u64,
-    /// Output directory for CSV artifacts. Defaults to target/engine-bench/<mode>-<timestamp>.
+    /// Output directory for CSV artifacts. Defaults to `target/engine-bench/<mode>-<timestamp>`.
     #[arg(long, short, value_name = "OUTPUT_DIR")]
     pub output: Option<PathBuf>,
 }

crates/eth-engine/src/engine.rs

@@ -107,7 +107,7 @@ pub trait EthereumAPI: Send + Sync {
 pub type IsOsakaActiveFn = Arc<dyn Fn(u64) -> bool + Send + Sync>;
 
 /// Ethereum engine implementation.
-/// Spec: https://github.com/ethereum/execution-apis/tree/main/src/engine
+/// Spec: <https://github.com/ethereum/execution-apis/tree/main/src/engine>
 #[derive(Clone)]
 pub struct Engine(Arc<Inner>);
 

crates/eth-engine/src/persistence_meter.rs

@@ -49,7 +49,7 @@ const MAX_RECONNECT_BACKOFF: Duration = Duration::from_secs(60);
 /// Tracks execution layer block persistence and applies backpressure when the
 /// EL falls behind.
 ///
-/// Callers invoke [`wait_for_persisted_block`] after submitting a block to the
+/// Callers invoke [`PersistenceMeter::wait_for_persisted_block`] after submitting a block to the
 /// EL. The call returns immediately if the EL has already persisted within the
 /// configured threshold, or blocks until persistence catches up. Returns `Err`
 /// on timeout.
@@ -114,26 +114,26 @@ struct SharedState {
     /// Wakes waiters when `last_persisted_block` advances or connection state changes.
     notify: Notify,
     /// Subscription lifecycle state. Backpressure is only enforced when
-    /// [`SUBSCRIPTION_STATUS_ACTIVE`].
+    /// `SUBSCRIPTION_STATUS_ACTIVE`.
     subscription_status: AtomicU8,
 }
 
 /// Meter block ingestion throughput using the execution layer's persisted block subscription.
 ///
 /// A background task maintains the subscription connection, updates an atomic
 /// counter on each notification, and wakes any waiters via [`Notify`]. This
-/// allows [`wait_for_persisted_block`] to return immediately when the
+/// allows [`PersistenceMeter::wait_for_persisted_block`] to return immediately when the
 /// canonical-minus-persisted gap is already below the configured threshold,
 /// and multiple callers can wait concurrently without contending on a lock.
 ///
 /// In the background, a task will maintain the connection, reconnecting as needed.
-/// When reconnecting, the internal [`subscription_status`] will transition to [`SUBSCRIPTION_STATUS_RECONNECTING`]
-/// which disables backpressure. Upon the first received notification, it will transition back to [`SUBSCRIPTION_STATUS_ACTIVE`],
+/// When reconnecting, the internal `subscription_status` will transition to `SUBSCRIPTION_STATUS_RECONNECTING`
+/// which disables backpressure. Upon the first received notification, it will transition back to `SUBSCRIPTION_STATUS_ACTIVE`,
 /// applying backpressure again.
 ///
 /// Seeding the meter with an initial height value will transition it to
-/// [`SUBSCRIPTION_STATUS_ACTIVE`] only if the subscription is already
-/// [`SUBSCRIPTION_STATUS_CONNECTED`]. If reconnecting, the seed updates the
+/// `SUBSCRIPTION_STATUS_ACTIVE` only if the subscription is already
+/// `SUBSCRIPTION_STATUS_CONNECTED`. If reconnecting, the seed updates the
 /// counter but backpressure remains suspended until the subscription is live.
 pub struct PersistedBlockMeter {
     shared: Arc<SharedState>,

crates/eth-engine/src/rpc/errors.rs

@@ -22,7 +22,7 @@ use jsonrpsee_types::error::ErrorObject;
 use thiserror::Error;
 
 /// Error codes taken from reth's code.
-/// See https://github.com/paradigmxyz/reth/blob/7345e1e5b5b88e53c4b3f3152078653507d0d26f/crates/rpc/rpc-engine-api/src/error.rs
+/// See <https://github.com/paradigmxyz/reth/blob/7345e1e5b5b88e53c4b3f3152078653507d0d26f/crates/rpc/rpc-engine-api/src/error.rs>
 ///
 /// Code used by reth for EngineApiError::UnknownPayload.
 const UNKNOWN_PAYLOAD_CODE: i32 = -38001;

crates/evm-node/src/engine.rs

@@ -15,7 +15,7 @@
 // limitations under the License.
 
 //! Arc validator
-//! fork from https://github.com/paradigmxyz/reth/blob/main/crates/ethereum/node/src/engine.rs
+//! fork from <https://github.com/paradigmxyz/reth/blob/main/crates/ethereum/node/src/engine.rs>
 //! - customize validate_payload_attributes_against_header to relax the timestamp constraint.
 
 use alloy_consensus::BlockHeader;
@@ -60,7 +60,7 @@ impl<ChainSpec> ArcEngineValidator<ChainSpec> {
     }
 }
 
-/// Type that validates an [`ExecutionPayload`].
+/// Type that validates an `ExecutionPayload`.
 impl<ChainSpec, Types> PayloadValidator<Types> for ArcEngineValidator<ChainSpec>
 where
     ChainSpec: EthChainSpec + EthereumHardforks + 'static,

crates/evm-node/src/node.rs

@@ -15,7 +15,7 @@
 // limitations under the License.
 
 //! Arc Node types config.
-//! Fork from https://github.com/paradigmxyz/reth/blob/v1.7.0/crates/ethereum/node/src/node.rs
+//! Fork from <https://github.com/paradigmxyz/reth/blob/v1.7.0/crates/ethereum/node/src/node.rs>
 //! Reference to EthereumNode and add our customization
 //! - inject the EVM customization in ArcExecutorBuilder
 //! - inject our consensus ArcConsensus in ArcConsensusBuilder

crates/evm-node/src/payload.rs

@@ -15,7 +15,7 @@
 // limitations under the License.
 
 //! Arc payload attributes builder for dev-mode local mining.
-//! Fork from https://github.com/paradigmxyz/reth/blob/v1.11.3/crates/engine/local/src/payload.rs
+//! Fork from <https://github.com/paradigmxyz/reth/blob/v1.11.3/crates/engine/local/src/payload.rs>
 //! - Uses `max(parent.timestamp, wall_clock)` instead of `max(parent.timestamp + 1, wall_clock)`
 //!   to allow equal timestamps, matching Arc's relaxed validation.
 

crates/evm-specs-tests/src/adapter.rs

@@ -117,7 +117,7 @@ pub fn build_default_arc_chain_spec() -> Arc<ArcChainSpec> {
 /// Build the ArcEvmFactory from a chain spec.
 ///
 /// Note: ArcEvmFactory::new takes a single arg (chain_spec).
-/// The struct is #[non_exhaustive] so the API may expand in the future.
+/// The struct is `#[non_exhaustive]` so the API may expand in the future.
 pub fn build_evm_factory(chain_spec: Arc<ArcChainSpec>) -> ArcEvmFactory {
     ArcEvmFactory::new(chain_spec)
 }

crates/evm/src/evm.rs

@@ -1253,7 +1253,7 @@ where
     /// Override `inspect_frame_init` to make subcall precompiles transparent in traces.
     ///
     /// For subcall precompiles (e.g. CallFrom): uses [`SubcallPrecompile::trace_child_call`]
-    /// to obtain the child's `CallInputs`, then passes them to [`ArcEvm::inspect_frame_init_impl`]
+    /// to obtain the child's `CallInputs`, then passes them to `ArcEvm::inspect_frame_init_impl`
     /// so the trace node shows the logical child call
     /// (spoofed_sender → target) instead of the precompile address.
     ///

crates/evm/src/executor.rs

@@ -87,7 +87,7 @@ impl<H, T> TxResult for ArcTxResult<H, T> {
 
 /// Custom block executor for Arc
 ///
-/// This functionality is mostly forked from: https://github.com/alloy-rs/evm/blob/v0.23.2/crates/evm/src/eth/block.rs
+/// This functionality is mostly forked from: <https://github.com/alloy-rs/evm/blob/v0.23.2/crates/evm/src/eth/block.rs>
 /// with modifications to support Arc-specific functionality.
 pub struct ArcBlockExecutor<'a, Evm, Spec, R: ReceiptBuilder> {
     /// Context for block execution.

crates/execution-payload/src/payload.rs

@@ -379,7 +379,7 @@ fn dump_tx_data(bytes: &[u8]) -> String {
 }
 
 /// Arc's Custom payload builder based on upstream Reth:
-/// https://github.com/paradigmxyz/reth/blob/74351d98e906b8af5f118694529fb2b71d316946/crates/ethereum/payload/src/lib.rs#L138
+/// <https://github.com/paradigmxyz/reth/blob/74351d98e906b8af5f118694529fb2b71d316946/crates/ethereum/payload/src/lib.rs#L138>
 /// Enforces a time budget to avoid overruns under heavy mempool load.
 /// The rest is following the logic in EthereumPayloadBuilder.
 #[derive(Debug, Clone, PartialEq, Eq)]

crates/execution-txpool/src/pool.rs

@@ -32,7 +32,7 @@ use reth_transaction_pool::{blobstore::DiskFileBlobStore, TransactionValidationT
 
 /// A basic Arc transaction pool builder.
 ///
-/// Fork from https://github.com/paradigmxyz/reth/blob/v1.7.0/crates/ethereum/node/src/node.rs#L435-L509
+/// Fork from <https://github.com/paradigmxyz/reth/blob/v1.7.0/crates/ethereum/node/src/node.rs#L435-L509>
 /// with customization to use ArcTransactionValidator.
 ///
 /// This contains various settings that can be configured and take precedence over the node's

crates/malachite-cli/src/cmd/start.rs

@@ -102,7 +102,7 @@ pub struct StartCmd {
     /// Gossipsub network load profile controlling mesh size and bandwidth.
     ///
     /// - low:     fewer mesh peers, lower bandwidth (mesh_n=3)
-    /// - average: balanced for typical deployments (mesh_n=6) [default]
+    /// - average: balanced for typical deployments (mesh_n=6) `[default]`
     /// - high:    more mesh peers, higher bandwidth (mesh_n=10)
     #[clap(
         long = "gossipsub.load",
@@ -462,10 +462,10 @@ pub struct StartCmd {
     /// (scheme http->ws / https->wss, port HTTP+1 if non-default).
     ///
     /// Examples:
-    ///   http://validator1:8545,ws=8546
-    ///   https://validator1:8545,wss=8546
-    ///   https://example.com,wss=ws.example.com
-    ///   https://example.com,wss=ws.example.com:1212
+    ///   `http://validator1:8545,ws=8546`
+    ///   `https://validator1:8545,wss=8546`
+    ///   `https://example.com,wss=ws.example.com`
+    ///   `https://example.com,wss=ws.example.com:1212`
     #[clap(long = "follow.endpoint", value_name = "ENDPOINT", requires = "follow")]
     #[serde(skip)]
     pub follow_endpoints: Vec<SyncEndpointUrl>,

crates/precompiles/src/call_from.rs

@@ -49,7 +49,7 @@ pub const CALL_FROM_ADDRESS: Address = address!("1800000000000000000000000000000
 ///
 /// Covers selector matching plus the fixed-size ABI head: 2 address words + 1 offset word +
 /// 1 length word. The dynamic `bytes data` payload is charged separately at
-/// [`COPY`] gas per 32-byte word (see [`abi_decode_gas`]).
+/// `COPY` gas per 32-byte word (see [`abi_decode_gas`]).
 pub const ABI_DECODE_BASE_GAS: u64 = 100;
 
 /// Computes total init_subcall gas: base overhead + ceil(data.len() / 32) * COPY.

crates/quake/src/latency.rs

@@ -131,7 +131,7 @@ impl Region {
 /// Regions ordered alphabetically by AWS region name.
 ///
 /// Note: Values are ONE-WAY latencies (RTT / 2).
-/// Source: https://www.cloudping.co/ (P50 median, 1 month) which reports RTT values.
+/// Source: <https://www.cloudping.co/> (P50 median, 1 month) which reports RTT values.
 /// We divide by 2 because `tc netem delay` applies one-way delay per direction.
 #[rustfmt::skip]
 pub(crate) const AWS_LATENCY_MATRIX: [[u32; 14]; 14] = [

crates/quake/src/main.rs

@@ -305,13 +305,13 @@ enum Commands {
     ///   warmup_s           30                   Seconds before first Prometheus scrape
     ///   duration_s         60                   Observation window / load duration
     ///   load_rate          50                   TPS during observation (0 = no load)
-    ///   load_targets       RPC_NODES            Node names and/or [node_groups] selectors (default group)
+    ///   load_targets       RPC_NODES            Node names and/or `node_groups` selectors (default group)
     ///   load_mix           transfer=100         Tx type mix
     ///   block_time_p50_ms  550                  Max p50 block time threshold for validators
     ///   block_time_p99_ms  1000                 Max p99 block time threshold for validators
     ///   sanity             true                 Run sanity phases
     ///   sync_speed         true                 Run sync speed test (destructive)
-    ///   arc_nodes          ARC_NODES group      Sanity target nodes (names and/or [node_groups])
+    ///   arc_nodes          ARC_NODES group      Sanity target nodes (names and/or `node_groups`)
     ///   snapshot_provider  full-circle-5        Snapshot source node
     ///   reference          validator-blue       Reference node for tip height
     ///   sync_nodes         full-quicknode-1     Nodes to sync-test
@@ -758,7 +758,7 @@ pub(crate) enum DownloadSubcommand {
         /// Metric names to download (all metrics if not specified)
         #[clap(last = true)]
         metric_names: Vec<String>,
-        /// Output file path (default: ./quake-metrics-<timestamp>.tar.gz)
+        /// Output file path (default: `./quake-metrics-<timestamp>.tar.gz`)
         #[clap(short = 'o', long)]
         output: Option<PathBuf>,
     },
@@ -775,7 +775,7 @@ pub(crate) enum DownloadSubcommand {
         /// Download only consensus layer (Malachite) data
         #[clap(long)]
         consensus_only: bool,
-        /// Output file path (default: ./quake-db-<timestamp>.tar.gz)
+        /// Output file path (default: `./quake-db-<timestamp>.tar.gz`)
         #[clap(short = 'o', long)]
         output: Option<PathBuf>,
     },

crates/quake/src/node.rs

@@ -153,7 +153,7 @@ impl Container {
 
     /// Build a private IP address from the given subnet, container, and node indexes (for local mode)
     ///
-    /// Format: "172.<subnet>.<container>.<node>" where:
+    /// Format: `"172.<subnet>.<container>.<node>"` where:
     /// - subnet index starts at 21
     /// - container index is 1 for CL and 2 for EL
     /// - node index starts at 0

crates/quake/src/report.rs

@@ -1160,7 +1160,7 @@ fn render_liveness_note(out: &mut String, liveness: &LivenessSection) {
     let _ = writeln!(out);
 }
 
-/// When a section failed, append the first few [`failures`] entries so the Summary
+/// When a section failed, append the first few `failures` entries so the Summary
 /// table explains *why* without reading the `## Failures` section. Values are
 /// single-lined and `|`-safe for markdown tables.
 fn format_summary_with_failures(summary: &str, passed: bool, failures: &[String]) -> String {

crates/quake/src/tests/types.rs

@@ -216,7 +216,7 @@ pub(crate) type TestFn =
     for<'a> fn(&'a Testnet, &'a RpcClientFactory, &'a TestParams) -> TestResult<'a>;
 
 /// Test registration submitted via the inventory system.
-/// This is used by the #[quake_test] macro to automatically register tests.
+/// This is used by the `#[quake_test]` macro to automatically register tests.
 pub(crate) struct TestRegistration {
     pub(crate) group: &'static str,
     pub(crate) name: &'static str,

crates/quake/src/valset.rs

@@ -20,7 +20,7 @@ use crate::node::NodeName;
 
 /// A validator power update consisting of a validator name and new voting power.
 /// This is what quake's `valset` command parses from a string of the form
-/// [<validator>:<voting_power>] given as input to the command.
+/// `<validator>:<voting_power>` given as input to the command.
 #[derive(Debug, Clone)]
 pub(crate) struct ValidatorPowerUpdate {
     /// Validator identifier, e.g., validator1

crates/test/checks/src/fetch.rs

@@ -28,7 +28,7 @@ const MAX_CONCURRENT_FETCHES: usize = 10;
 /// Returns `(node_name, raw_metrics_text)` pairs. Nodes that fail to respond
 /// return an empty string for their metrics text.
 ///
-/// Concurrency is capped at [`MAX_CONCURRENT_FETCHES`] to avoid overwhelming
+/// Concurrency is capped at `MAX_CONCURRENT_FETCHES` to avoid overwhelming
 /// narrow transports like SSM tunnels.
 pub async fn fetch_all_metrics(metrics_urls: &[(String, Url)]) -> Vec<(String, String)> {
     let mut sorted_urls: Vec<_> = metrics_urls.to_vec();

crates/test/checks/src/perf.rs

@@ -336,7 +336,7 @@ fn delta_histogram_stats(
 /// Parse performance metrics from the **delta** between two scrapes per node.
 ///
 /// Only nodes present in **both** scrapes are included (intersection by
-/// [`display_name_for_scrape`], same pairing idea as [`crate::health::compute_health_deltas`]).
+/// `display_name_for_scrape`, same pairing idea as [`crate::health::compute_health_deltas`]).
 /// Histograms use the same metric names as [`parse_perf_metrics`]; percentiles apply to
 /// observations recorded between the two scrapes.
 pub fn parse_perf_metrics_delta(

crates/types/src/address.rs

@@ -59,7 +59,7 @@ impl Address {
         self.0.into()
     }
 
-    /// Creates a new [`FixedBytes`] where all bytes are set to `byte`.
+    /// Creates a new [`Address`] where all bytes are set to `byte`.
     #[inline]
     pub const fn repeat_byte(byte: u8) -> Self {
         Self(AlloyAddress::repeat_byte(byte))