docs: clean up payload builder docs (#4380)

crates/payload/basic/src/lib.rs

@@ -11,7 +11,7 @@
     attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
 ))]
 
-//! reth basic payload job generator
+//! A basic payload generator for reth.
 
 use crate::metrics::PayloadBuilderMetrics;
 use futures_core::ready;
@@ -60,7 +60,7 @@ use tracing::{debug, trace};
 
 mod metrics;
 
-/// The [PayloadJobGenerator] that creates [BasicPayloadJob]s.
+/// The [`PayloadJobGenerator`] that creates [`BasicPayloadJob`]s.
 pub struct BasicPayloadJobGenerator<Client, Pool, Tasks, Builder = ()> {
     /// The client that can interact with the chain.
     client: Client,

crates/payload/builder/src/database.rs

@@ -10,7 +10,7 @@ use std::{
     collections::{hash_map::Entry, HashMap},
 };
 
-/// A container type that caches all [DatabaseRef] reads from an underlying [DatabaseRef].
+/// A container type that caches reads from an underlying [DatabaseRef].
 ///
 /// This is intended to be used in conjunction with [CacheDB](reth_revm_primitives::db::CacheDB)
 /// during payload building which repeatedly accesses the same data.

crates/payload/builder/src/lib.rs

@@ -16,27 +16,30 @@
     attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
 ))]
 
-//! This crate defines the abstractions to create and update payloads:
+//! This crate defines abstractions to create and update payloads (blocks):
-//!   - [PayloadJobGenerator]: a type that knows how to create new jobs for creating payloads based
+//! - [`PayloadJobGenerator`]: a type that knows how to create new jobs for creating payloads based
-//!     on [PayloadAttributes](reth_rpc_types::engine::PayloadAttributes).
+//!   on [`PayloadAttributes`](reth_rpc_types::engine::PayloadAttributes).
-//!   - [PayloadJob]: a type that can yields (better) payloads over time.
+//! - [`PayloadJob`]: a type that yields (better) payloads over time.
 //!
-//! This crate comes with the generic [PayloadBuilderService] responsible for managing payload jobs.
+//! This crate comes with the generic [`PayloadBuilderService`] responsible for managing payload
+//! jobs.
 //!
 //! ## Node integration
 //!
-//! In a standard node the [PayloadBuilderService] sits downstream of the engine API or rather the
+//! In a standard node the [`PayloadBuilderService`] sits downstream of the engine API, or rather
-//! component that handles requests from the Beacon Node like `engine_forkchoiceUpdatedV1`.
+//! the component that handles requests from the consensus layer like `engine_forkchoiceUpdatedV1`.
+//!
 //! Payload building is enabled if the forkchoice update request contains payload attributes.
-//! See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/shanghai.md#engine_forkchoiceupdatedv2>
+//!
-//! If the forkchoice update request is VALID and contains payload attributes the
+//! See also [the engine API docs](https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/shanghai.md#engine_forkchoiceupdatedv2)
-//! [PayloadBuilderService] will create a new [PayloadJob] via the [PayloadJobGenerator] and start
+//! If the forkchoice update request is `VALID` and contains payload attributes the
-//! polling it until the payload is requested by the CL and the payload job is resolved:
+//! [`PayloadBuilderService`] will create a new [`PayloadJob`] via the given [`PayloadJobGenerator`]
-//! [PayloadJob::resolve]
+//! and start polling it until the payload is requested by the CL and the payload job is resolved
+//! (see [`PayloadJob::resolve`]).
 //!
 //! ## Example
 //!
-//! A simple example of a [PayloadJobGenerator] that creates empty blocks:
+//! A simple example of a [`PayloadJobGenerator`] that creates empty blocks:
 //!
 //! ```
 //! use std::future::Future;

crates/payload/builder/src/service.rs

@@ -124,10 +124,10 @@ impl PayloadBuilderHandle {
 ///
 /// This type is an endless future that manages the building of payloads.
 ///
-/// It tracks active payloads and their build jobs that run in the worker pool.
+/// It tracks active payloads and their build jobs that run in a worker pool.
 ///
-/// By design, this type relies entirely on the [PayloadJobGenerator] to create new payloads and
+/// By design, this type relies entirely on the [`PayloadJobGenerator`] to create new payloads and
-/// does know nothing about how to build them, itt just drives the payload jobs.
+/// does know nothing about how to build them, it just drives their jobs to completion.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct PayloadBuilderService<Gen>
 where
@@ -141,7 +141,7 @@ where
     _service_tx: mpsc::UnboundedSender<PayloadServiceCommand>,
     /// Receiver half of the command channel.
     command_rx: UnboundedReceiverStream<PayloadServiceCommand>,
-    /// metrics for the payload builder service
+    /// Metrics for the payload builder service
     metrics: PayloadBuilderServiceMetrics,
 }
 

crates/payload/builder/src/traits.rs

@@ -5,14 +5,15 @@ use std::{future::Future, sync::Arc};
 
 /// A type that can build a payload.
 ///
-/// This type is a Future that resolves when the job is done (e.g. timed out) or it failed. It's not
+/// This type is a [`Future`] that resolves when the job is done (e.g. complete, timed out) or it
-/// supposed to return the best payload built when it resolves instead [PayloadJob::best_payload]
+/// failed. It's not supposed to return the best payload built when it resolves, instead
-/// should be used for that.
+/// [`PayloadJob::best_payload`] should be used for that.
 ///
-/// A PayloadJob must always be prepared to return the best payload built so far to make there's a
+/// A `PayloadJob` must always be prepared to return the best payload built so far to ensure there
-/// valid payload to deliver to the CL, so it does not miss a slot, even if the payload is empty.
+/// is a valid payload to deliver to the CL, so it does not miss a slot, even if the payload is
+/// empty.
 ///
-/// Note: A PayloadJob need to be cancel safe because it might be dropped after the CL has requested the payload via `engine_getPayloadV1`, See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/paris.md#engine_getpayloadv1>
+/// Note: A `PayloadJob` need to be cancel safe because it might be dropped after the CL has requested the payload via `engine_getPayloadV1` (see also [engine API docs](https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/paris.md#engine_getpayloadv1))
 pub trait PayloadJob: Future<Output = Result<(), PayloadBuilderError>> + Send + Sync {
     /// Represents the future that resolves the block that's returned to the CL.
     type ResolvePayloadFuture: Future<Output = Result<Arc<BuiltPayload>, PayloadBuilderError>>
@@ -29,9 +30,11 @@ pub trait PayloadJob: Future<Output = Result<(), PayloadBuilderError>> + Send +
     ///
     /// This is invoked on [`engine_getPayloadV2`](https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#engine_getpayloadv2) and [`engine_getPayloadV1`](https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#engine_getpayloadv1).
     ///
-    /// The timeout for returning the payload to the CL is 1s.
+    /// The timeout for returning the payload to the CL is 1s, thus the future returned should
-    /// Ideally, future returned by this method must resolve in under 1s. Ideally this is the best
+    /// resolve in under 1 second.
-    /// payload built so far or an empty block without transactions if nothing has been built yet.
+    ///
+    /// Ideally this is the best payload built so far, or an empty block without transactions, if
+    /// nothing has been built yet.
     ///
     /// According to the spec:
     /// > Client software MAY stop the corresponding build process after serving this call.
@@ -39,9 +42,9 @@ pub trait PayloadJob: Future<Output = Result<(), PayloadBuilderError>> + Send +
     /// It is at the discretion of the implementer whether the build job should be kept alive or
     /// terminated.
     ///
-    /// If this returns [KeepPayloadJobAlive::Yes] then the future the [PayloadJob] will be polled
+    /// If this returns [`KeepPayloadJobAlive::Yes`], then the [`PayloadJob`] will be polled
-    /// once more, if this returns [KeepPayloadJobAlive::No] then the [PayloadJob] will be dropped
+    /// once more. If this returns [`KeepPayloadJobAlive::No`] then the [`PayloadJob`] will be
-    /// after this call
+    /// dropped after this call.
     fn resolve(&mut self) -> (Self::ResolvePayloadFuture, KeepPayloadJobAlive);
 }
 
@@ -59,15 +62,17 @@ pub enum KeepPayloadJobAlive {
 pub trait PayloadJobGenerator: Send + Sync {
     /// The type that manages the lifecycle of a payload.
     ///
-    /// This type is a Stream that yields better payloads.
+    /// This type is a future that yields better payloads.
     type Job: PayloadJob;
 
-    /// Creates the initial payload and a new [PayloadJob] that yields better payloads.
+    /// Creates the initial payload and a new [`PayloadJob`] that yields better payloads over time.
     ///
     /// This is called when the CL requests a new payload job via a fork choice update.
     ///
-    /// Note: this is expected to build a new (empty) payload without transactions, so it can be
+    /// # Note
-    /// returned directly. when asked for
+    ///
+    /// This is expected to initially build a new (empty) payload without transactions, so it can be
+    /// returned directly.
     fn new_payload_job(
         &self,
         attr: PayloadBuilderAttributes,