From 1d56382b8d4c4e75243ca8ab4e058ad0ad95e713 Mon Sep 17 00:00:00 2001
From: James Prestwich <james@prestwi.ch>
Date: Wed, 25 Sep 2024 11:37:25 -0400
Subject: [PATCH] doc: update some exexhead docs (#11214)

---
 crates/exex/exex/src/notifications.rs | 9 ++++++---
 crates/exex/types/src/head.rs         | 4 +++-
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/crates/exex/exex/src/notifications.rs b/crates/exex/exex/src/notifications.rs
index ce954e42a3..54d7959dc5 100644
--- a/crates/exex/exex/src/notifications.rs
+++ b/crates/exex/exex/src/notifications.rs
@@ -100,10 +100,13 @@ where
     P: BlockReader + HeaderProvider + StateProviderFactory + Clone + Unpin + 'static,
     E: BlockExecutorProvider + Clone + Unpin + 'static,
 {
-    /// Subscribe to notifications with the given head.
+    /// Subscribe to notifications with the given head. This head is the ExEx's
+    /// latest view of the host chain.
     ///
-    /// Notifications will be sent starting from the head, not inclusive. For example, if
-    /// `head.number == 10`, then the first notification will be with `block.number == 11`.
+    /// Notifications will be sent starting from the head, not inclusive. For
+    /// example, if `head.number == 10`, then the first notification will be
+    /// with `block.number == 11`. A `head.number` of 10 indicates that the ExEx
+    /// has processed up to block 10, and is ready to process block 11.
     pub fn with_head(self, head: ExExHead) -> ExExNotificationsWithHead<P, E> {
         ExExNotificationsWithHead::new(
             self.node_head,
diff --git a/crates/exex/types/src/head.rs b/crates/exex/types/src/head.rs
index 730b5724b3..8863ab327d 100644
--- a/crates/exex/types/src/head.rs
+++ b/crates/exex/types/src/head.rs
@@ -1,6 +1,8 @@
 use alloy_eips::BlockNumHash;
 
-/// A head of the ExEx. It determines the highest block committed to the internal ExEx state.
+/// A head of the ExEx. It contains the highest host block committed to the
+/// internal ExEx state. I.e. the latest block that the ExEx has fully
+/// processed.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ExExHead {
     /// The head block.