From c47418d9222f06ca82453dc5fe6a7051952d438c Mon Sep 17 00:00:00 2001
From: Sergey Penkovsky <sergey.penkovsky@gmail.com>
Date: Thu, 22 May 2025 15:18:16 +0300
Subject: [PATCH] update readme

---
 cherrypick_annotations/README.md | 61 +++++++++++++++++++++++++++-----
 1 file changed, 52 insertions(+), 9 deletions(-)

diff --git a/cherrypick_annotations/README.md b/cherrypick_annotations/README.md
index f2611a1..91deca2 100644
--- a/cherrypick_annotations/README.md
+++ b/cherrypick_annotations/README.md
@@ -10,9 +10,12 @@ A lightweight set of Dart annotations designed for dependency injection (DI) fra
 
 - **@module** – Marks a class as a DI module for service/provider registration.
 - **@singleton** – Declares that a method or class should be provided as a singleton.
+- **@instance** – Marks a method or class so that a new instance is provided on each request (not a singleton).
+- **@provide** – Marks a method whose return value should be registered as a provider, supporting dependency injection into parameters.
 - **@named** – Assigns a string name to a binding for keyed resolution.
+- **@params** – Indicates that a parameter should be injected with runtime-supplied arguments.
 
-These annotations are intended to streamline DI configuration and serve as markers for code generation tools.
+These annotations streamline DI configuration and serve as markers for code generation tools such as [`cherrypick_generator`](https://pub.dev/packages/cherrypick_generator).
 
 ---
 
@@ -25,7 +28,7 @@ dependencies:
   cherrypick_annotations: ^latest
 ```
 
-Add as a `dev_dependency` for codegen:
+Add as a `dev_dependency` for code generation:
 
 ```yaml
 dev_dependencies:
@@ -33,9 +36,7 @@ dev_dependencies:
   cherrypick_generator:
 ```
 
-### 2. Usage
-
-Annotate your DI modules and providers:
+### 2. Annotate your DI modules and providers
 
 ```dart
 import 'package:cherrypick_annotations/cherrypick_annotations.dart';
@@ -48,6 +49,15 @@ abstract class AppModule extends Module {
 
   @named('baseUrl')
   String baseUrl() => 'https://api.example.com';
+
+  @instance()
+  Foo foo() => Foo();
+
+  @provide()
+  Bar bar(Foo foo) => Bar(foo);
+
+  @provide()
+  String greet(@params() dynamic params) => 'Hello $params';
 }
 ```
 
@@ -59,6 +69,9 @@ final class $AppModule extends AppModule {
   void builder(Scope currentScope) {
     bind<Dio>().toProvide(() => dio()).singleton();
     bind<String>().toProvide(() => baseUrl()).withName('baseUrl');
+    bind<Foo>().toInstance(foo());
+    bind<Bar>().toProvide(() => bar(currentScope.resolve<Foo>()));
+    bind<String>().toProvideWithParams((args) => greet(args));
   }
 }
 ```
@@ -73,7 +86,7 @@ final class $AppModule extends AppModule {
 @module()
 abstract class AppModule extends Module {}
 ```
-Use on classes to mark them as a DI module.
+Use on classes to mark them as a DI module. This is the root for registering your dependency providers.
 
 ---
 
@@ -83,7 +96,27 @@ Use on classes to mark them as a DI module.
 @singleton()
 Dio dio() => Dio();
 ```
-Use on methods or classes to provide a singleton instance.
+Use on methods or classes to provide a singleton instance (the same instance is reused).
+
+---
+
+### `@instance`
+
+```dart
+@instance()
+Foo foo() => Foo();
+```
+Use on methods or classes to provide a new instance on each request (not a singleton).
+
+---
+
+### `@provide`
+
+```dart
+@provide()
+Bar bar(Foo foo) => Bar(foo);
+```
+Use on methods to indicate they provide a dependency to the DI module. Dependencies listed as parameters (e.g., `foo`) are resolved and injected.
 
 ---
 
@@ -93,7 +126,17 @@ Use on methods or classes to provide a singleton instance.
 @named('token')
 String token() => 'abc';
 ```
-Assigns a name to the binding for keyed injection.
+Assigns a name to a binding for keyed injection or resolution.
+
+---
+
+### `@params`
+
+```dart
+@provide()
+String greet(@params() dynamic params) => 'Hello $params';
+```
+Use on method parameters to indicate that this parameter should receive runtime-supplied arguments during dependency resolution (for example, via `.toProvide*((params) => greate(params))` in generated code).
 
 ---
 
@@ -111,4 +154,4 @@ Pull requests and feedback are welcome!
 
 ## Author
 
-Sergey Penkovsky (<sergey.penkovsky@gmail.com>)
+Sergey Penkovsky (<sergey.penkovsky@gmail.com>)
\ No newline at end of file