From 482b7b0f5f86c18d53a0ddf44a56aff45c1a163a Mon Sep 17 00:00:00 2001
From: Sergey Penkovsky <sergey.penkovsky@gmail.com>
Date: Mon, 8 Sep 2025 09:51:40 +0300
Subject: [PATCH] docs(binding): clarify  registration limitation in API doc

- Add an explicit warning and usage pattern examples to the toInstance() method doc-comment.
- Explain why resolving dependencies registered with toInstance inside the same Module.builder does not work.
- Reference safe and unsafe code samples for users navigating via IDE and API documentation.
---
 cherrypick/lib/src/binding.dart | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/cherrypick/lib/src/binding.dart b/cherrypick/lib/src/binding.dart
index c0e7e7e..c29011b 100644
--- a/cherrypick/lib/src/binding.dart
+++ b/cherrypick/lib/src/binding.dart
@@ -160,6 +160,38 @@ class Binding<T> {
   /// ```dart
   /// bind<Api>().toInstance(ApiMock());
   /// ```
+  ///
+  /// **Important limitation:**
+  /// If you register several dependencies via [toInstance] inside a [`Module.builder`],
+  /// do _not_ use `scope.resolve<T>()` to get objects that are also being registered during the _same_ builder execution.
+  /// All [toInstance] bindings are applied sequentially, and at the point of registration,
+  /// earlier objects are not yet available for resolve.
+  ///
+  /// **Correct:**
+  /// ```dart
+  /// void builder(Scope scope) {
+  ///   final a = A();
+  ///   final b = B(a);
+  ///   bind<A>().toInstance(a);
+  ///   bind<B>().toInstance(b);
+  /// }
+  /// ```
+  /// **Wrong:**
+  /// ```dart
+  /// void builder(Scope scope) {
+  ///   bind<A>().toInstance(A());
+  ///   bind<B>().toInstance(B(scope.resolve<A>())); // Error! A is not available yet.
+  /// }
+  /// ```
+  /// **Wrong:**
+  /// ```dart
+  /// void builder(Scope scope) {
+  ///   bind<A>().toProvide(() => A());
+  ///   bind<B>().toInstance(B(scope.resolve<A>())); // Error! A is not available yet.
+  /// }
+  /// ```
+  /// This restriction only applies to [toInstance] bindings.
+  /// With [toProvide]/[toProvideAsync] you may freely use `scope.resolve<T>()` in the builder or provider function.
   Binding<T> toInstance(Instance<T> value) {
     _resolver = InstanceResolver<T>(value);
     return this;