mirror of
https://github.com/pese-git/cherrypick.git
synced 2026-01-26 22:59:58 +00:00
docs(binding,docs): clarify .singleton() with .toInstance() behavior in docs and API
- Add an explicit note and warning about the effect (or lack thereof) of calling `.singleton()` after `.toInstance()`: - in singleton() API doc-comment in binding.dart, - in README.md (after all binding usage patterns), - in full_tutorial_en.md and full_tutorial_ru.md. - Explain that `.singleton()` has no effect on objects registered with `.toInstance()` — they are always single instance. - Recommend `.singleton()` only for providers (toProvide/toProvideAsync), not direct instances. - Improves clarity and prevents misuse/confusion for end users and future maintainers.
This commit is contained in:
@@ -185,6 +185,15 @@ void builder(Scope scope) {
|
||||
> Use this pattern only when you want a “master” singleton. If you expect a new instance per params, **do not** use `.singleton()` on parameterized providers.
|
||||
|
||||
|
||||
> ℹ️ **Note about `.singleton()` and `.toInstance()`:**
|
||||
>
|
||||
> Calling `.singleton()` after `.toInstance()` does **not** change the binding’s behavior: the object passed with `toInstance()` is already a single, constant instance that will be always returned for every resolve.
|
||||
>
|
||||
> It is not necessary to use `.singleton()` with an existing object—this call has no effect.
|
||||
>
|
||||
> `.singleton()` is only meaningful with providers (such as `toProvide`/`toProvideAsync`), to ensure only one instance is created by the factory.
|
||||
|
||||
|
||||
### Module
|
||||
|
||||
A **Module** is a logical collection point for bindings, designed for grouping and initializing related dependencies. Implement the `builder` method to define how dependencies should be bound within the scope.
|
||||
|
||||
@@ -258,6 +258,13 @@ class Binding<T> {
|
||||
/// ```
|
||||
///
|
||||
/// Use this pattern only if you want a master singleton. If you expect a new instance per params, **do not** use `.singleton()` on parameterized providers.
|
||||
///
|
||||
/// ℹ️ **Note about `.singleton()` and `.toInstance()`:**
|
||||
///
|
||||
/// Calling `.singleton()` after `.toInstance()` does **not** change the binding’s behavior:
|
||||
/// the object passed with `toInstance()` is already a single, constant instance that will always be returned for every resolve.
|
||||
/// There is no need to use `.singleton()` with `toInstance()`. This call has no effect.
|
||||
/// `.singleton()` is only meaningful with providers (`toProvide`, `toProvideAsync`, etc), to ensure only one instance is created by the factory.
|
||||
Binding<T> singleton() {
|
||||
_resolver?.toSingleton();
|
||||
return this;
|
||||
|
||||
Reference in New Issue
Block a user