chore: improve forkchoiceUpdated doc comments (paradigmxyz#5925)

crates/rpc/rpc-api/src/engine.rs

@@ -35,23 +35,35 @@ pub trait EngineApi {
 
     /// See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/paris.md#engine_forkchoiceupdatedv1>
     ///
-    /// Caution: This should not accept the `withdrawals` field
+    /// Caution: This should not accept the `withdrawals` field in the payload attributes.
     #[method(name = "forkchoiceUpdatedV1")]
     async fn fork_choice_updated_v1(
         &self,
         fork_choice_state: ForkchoiceState,
         payload_attributes: Option<PayloadAttributes>,
     ) -> RpcResult<ForkchoiceUpdated>;
 
+    /// Post Shanghai forkchoice update handler
+    ///
+    /// This is the same as `forkchoiceUpdatedV1`, but expects an additional `withdrawals` field in
+    /// the [PayloadAttributes], if payload attributes are provided.
+    ///
     /// See also <https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/shanghai.md#engine_forkchoiceupdatedv2>
+    ///
+    /// Caution: This should not accept the `parentBeaconBlockRoot` field in the payload
+    /// attributes.
     #[method(name = "forkchoiceUpdatedV2")]
     async fn fork_choice_updated_v2(
         &self,
         fork_choice_state: ForkchoiceState,
         payload_attributes: Option<PayloadAttributes>,
     ) -> RpcResult<ForkchoiceUpdated>;
 
-    /// Same as `forkchoiceUpdatedV2` but supports additional [PayloadAttributes] field.
+    /// Post Cancun forkchoice update handler
+    ///
+    /// This is the same as `forkchoiceUpdatedV2`, but expects an additional
+    /// `parentBeaconBlockRoot` field in the the [PayloadAttributes], if payload attributes are
+    /// provided.
     ///
     /// See also <https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#engine_forkchoiceupdatedv3>
     #[method(name = "forkchoiceUpdatedV3")]