From ea2b6687f4f7ad102bbf705923b4921fffa3ecc9 Mon Sep 17 00:00:00 2001
From: Sergey Penkovsky <sergey.penkovsky@gmail.com>
Date: Tue, 12 Aug 2025 00:17:46 +0300
Subject: [PATCH] docs: add full English documentation and usage guide to
 README.md

---
 talker_cherrypick_logger/README.md | 127 ++++++++++++++++++++++++-----
 1 file changed, 105 insertions(+), 22 deletions(-)

diff --git a/talker_cherrypick_logger/README.md b/talker_cherrypick_logger/README.md
index 8831761..101bf38 100644
--- a/talker_cherrypick_logger/README.md
+++ b/talker_cherrypick_logger/README.md
@@ -1,39 +1,122 @@
-<!-- 
-This README describes the package. If you publish this package to pub.dev,
-this README's contents appear on the landing page for your package.
+# talker_cherrypick_logger
 
-For information about how to write a good package README, see the guide for
-[writing package pages](https://dart.dev/tools/pub/writing-package-pages). 
+An integration package that allows you to log [CherryPick](https://github.com/pese-dot-work/cherrypick) Dependency Injection (DI) container events using the [Talker](https://pub.dev/packages/talker) logging system.  
+All CherryPick lifecycle events, instance creations, cache operations, module activities, cycles, and errors are routed directly to your Talker logger for easy debugging and advanced diagnostics.
 
-For general information about developing packages, see the Dart guide for
-[creating packages](https://dart.dev/guides/libraries/create-packages)
-and the Flutter guide for
-[developing packages and plugins](https://flutter.dev/to/develop-packages). 
--->
-
-TODO: Put a short description of the package here that helps potential users
-know whether this package might be useful for them.
+---
 
 ## Features
 
-TODO: List what your package can do. Maybe include images, gifs, or videos.
+- **Automatic DI container logging:**  
+  All core CherryPick events (instance creation/disposal, cache hits/misses, module install/removal, scopes, cycles, errors) are logged through Talker.
+- **Flexible log levels:**  
+  Each event uses the appropriate Talker log level (`info`, `warning`, `verbose`, `handle` for errors).
+- **Works with any Talker setup:**  
+  No extra dependencies required except Talker and CherryPick.
+- **Improves debugging and DI transparency** in both development and production.
+
+---
 
 ## Getting started
 
-TODO: List prerequisites and provide or point to information on how to
-start using the package.
+### 1. Add dependencies
+
+In your `pubspec.yaml`:
+```yaml
+dependencies:
+  cherrypick: ^latest
+  talker: ^latest
+  talker_cherrypick_logger:
+    git:
+      url: https://github.com/pese-dot-work/cherrypick.git
+      path: talker_cherrypick_logger
+```
+
+### 2. Import the package
+```dart
+import 'package:talker/talker.dart';
+import 'package:cherrypick/cherrypick.dart';
+import 'package:talker_cherrypick_logger/talker_cherrypick_logger.dart';
+```
+
+---
 
 ## Usage
 
-TODO: Include short and useful examples for package users. Add longer examples
-to `/example` folder. 
+### Basic integration
+
+1. **Create a Talker instance** (optionally customize Talker as you wish):
+    ```dart
+    final talker = Talker();
+    ```
+
+2. **Create the observer and pass it to CherryPick:**
+    ```dart
+    final observer = TalkerCherryPickObserver(talker);
+
+    // On DI setup, pass observer when opening (or re-opening) root or any custom scope
+    CherryPick.openRootScope(observer: observer);
+    ```
+
+3. **Now all DI events appear in your Talker logs!**
+
+#### Example log output
+
+- `[binding][CherryPick] MyService — MyServiceImpl (scope: root)`
+- `[create][CherryPick] MyService — MyServiceImpl => Instance(...) (scope: root)`
+- `[cache hit][CherryPick] MyService — MyServiceImpl (scope: root)`
+- `[cycle][CherryPick] Detected: A -> B -> C -> A (scope: root)`
+- `[error][CherryPick] Failed to resolve dependency`
+- `[diagnostic][CherryPick] Cache cleared`
+
+#### How it works
+
+`TalkerCherryPickObserver` implements `CherryPickObserver` and routes all methods/events to Talker:
+- Regular events: `.info()`  
+- DI Warnings and cycles: `.warning()`  
+- Diagnostics: `.verbose()`  
+- Errors: `.handle()` (so they are visible in Talker error console, with stack trace)
+
+---
+
+## Extended example
 
 ```dart
-const like = 'sample';
+import 'package:cherrypick/cherrypick.dart';
+import 'package:talker/talker.dart';
+import 'package:talker_cherrypick_logger/talker_cherrypick_logger.dart';
+
+void main() {
+  final talker = Talker();
+  final observer = TalkerCherryPickObserver(talker);
+
+  // Optionally: customize Talker output or filtering
+  // talker.settings.logLevel = TalkerLogLevel.debug;
+
+  CherryPick.openRootScope(observer: observer);
+
+  // ...setup your DI modules as usual
+  // All container events will appear in Talker logs for easy debugging!
+}
 ```
 
+---
+
 ## Additional information
 
-TODO: Tell users more about the package: where to find more information, how to 
-contribute to the package, how to file issues, what response they can expect 
-from the package authors, and more.
+- This package is especially useful for debugging large or layered projects using CherryPick.
+- For advanced Talker configurations (UI, outputs to remote, filtering), see the [Talker documentation](https://pub.dev/packages/talker).
+- This package does **not** interfere with DI graph construction or your app's behavior — it's purely diagnostic.
+- For questions or issues, open an issue on the main [cherrypick repository](https://github.com/pese-dot-work/cherrypick).
+
+---
+
+## Contributing
+
+Feel free to contribute improvements or report bugs via pull requests or issues!
+
+---
+
+## License
+
+See [LICENSE](LICENSE) for details.