From d0815e2a28c9efd03dd1aa8afad439c8a509a245 Mon Sep 17 00:00:00 2001
From: Sina Mahmoodi <1591639+s1na@users.noreply.github.com>
Date: Wed, 20 Apr 2022 16:12:45 +0200
Subject: [PATCH] pubsub: clarify what newHeads emits (#24722)

---
 docs/_rpc/pubsub.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/_rpc/pubsub.md b/docs/_rpc/pubsub.md
index 647445534b..e6eaaec35b 100644
--- a/docs/_rpc/pubsub.md
+++ b/docs/_rpc/pubsub.md
@@ -72,9 +72,9 @@ was cancelled successful.
 
 ### newHeads
 
-Fires a notification each time a new header is appended to the chain, including chain reorganizations. Users can use the bloom filter to determine if the block contains logs that are interested to them.
+Fires a notification each time a new header is appended to the chain, including chain reorganizations. Users can use the bloom filter to determine if the block contains logs that are interested to them. Note that if geth receives multiple blocks simultaneously, e.g. catching up after being out of sync, only the last block is emitted.
 
-In case of a chain reorganization the subscription will emit all new headers for the new
+In case of a chain reorganization the subscription will emit the last header in the new
 chain. Therefore the subscription can emit multiple headers on the same height.
 
 #### Example