From 8dfff11468a400b326f13797f32fcafd8bbc485b Mon Sep 17 00:00:00 2001
From: Facundo Farall <37149322+ffarall@users.noreply.github.com>
Date: Sat, 28 Sep 2024 04:59:49 -0400
Subject: [PATCH] Clarify firing of `import_notification_stream` in doc comment
 (#5811)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

# Description

Updates the doc comment on the `import_notification_stream` to make its
behaviour clearer.

Closes [Unexpected behaviour of block
`import_notification_stream`](https://github.com/paritytech/polkadot-sdk/issues/5596).

## Integration

Doesn't apply.

## Review Notes

The old comment docs caused some confusion to myself and some members of
my team, on when this notification stream is triggered. This is
reflected in the linked
[issue](https://github.com/paritytech/polkadot-sdk/issues/5596), and as
discussed there, this PR aims to prevent this confusion in future devs
looking to make use of this functionality.

# Checklist

* [x] My PR includes a detailed description as outlined in the
"Description" and its two subsections above.
* [ ] My PR follows the [labeling requirements](

https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CONTRIBUTING.md#Process
) of this project (at minimum one label for `T` required)
* External contributors: ask maintainers to put the right label on your
PR.
* [x] I have made corresponding changes to the documentation (if
applicable)
* [x] I have added tests that prove my fix is effective or that my
feature works (if applicable)

You can remove the "Checklist" section once all have been checked. Thank
you for your contribution!

---------

Co-authored-by: Michal Kucharczyk <1728078+michalkucharczyk@users.noreply.github.com>
Co-authored-by: Bastian Köcher <git@kchr.de>
---
 prdoc/pr_5811.prdoc                | 13 +++++++++++++
 substrate/client/api/src/client.rs | 13 ++++++++++---
 2 files changed, 23 insertions(+), 3 deletions(-)
 create mode 100644 prdoc/pr_5811.prdoc

diff --git a/prdoc/pr_5811.prdoc b/prdoc/pr_5811.prdoc
new file mode 100644
index 0000000000000..103fef4bb8b09
--- /dev/null
+++ b/prdoc/pr_5811.prdoc
@@ -0,0 +1,13 @@
+# Schema: Polkadot SDK PRDoc Schema (prdoc) v1.0.0
+# See doc at https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/prdoc/schema_user.json
+
+title: "Improve `import_notification_stream` documentation" 
+
+doc:
+  - audience: Node Dev
+    description: |
+      "Updates the doc comment on the `import_notification_stream` to make its behaviour clearer. Now it specifically states that this notification stream is fired on every import notification after the initial sync, and only when there are re-orgs in the initial sync."
+
+crates:
+  - name: sc-client-api
+    bump: patch
diff --git a/substrate/client/api/src/client.rs b/substrate/client/api/src/client.rs
index 45cfafb258463..764930984ed71 100644
--- a/substrate/client/api/src/client.rs
+++ b/substrate/client/api/src/client.rs
@@ -65,9 +65,16 @@ pub trait BlockOf {
 pub trait BlockchainEvents<Block: BlockT> {
 	/// Get block import event stream.
 	///
-	/// Not guaranteed to be fired for every imported block, only fired when the node
-	/// has synced to the tip or there is a re-org. Use `every_import_notification_stream()`
-	/// if you want a notification of every imported block regardless.
+	/// Not guaranteed to be fired for every imported block. Use
+	/// `every_import_notification_stream()` if you want a notification of every imported block
+	/// regardless.
+	///
+	/// The events for this notification stream are emitted:
+	/// - During initial sync process: if there is a re-org while importing blocks. See
+	/// [here](https://github.com/paritytech/substrate/pull/7118#issuecomment-694091901) for the
+	/// rationale behind this.
+	/// - After initial sync process: on every imported block, regardless of whether it is
+	/// the new best block or not, causes a re-org or not.
 	fn import_notification_stream(&self) -> ImportNotifications<Block>;
 
 	/// Get a stream of every imported block.