From 547a15fa4ea79878cca61d977a91653488b82eab Mon Sep 17 00:00:00 2001 From: Sergey Penkovsky Date: Mon, 4 Aug 2025 10:39:36 +0300 Subject: [PATCH] docs(faq): add best practice FAQ about using await with scope disposal - Added FAQ section in documentation (README and tutorials, EN + RU) recommending always using await when calling CherryPick.closeRootScope, scope.closeScope, or scope.dispose, even if no services implement Disposable. - Clarifies future-proof resource management for all users. --- cherrypick/README.md | 8 ++++++++ doc/full_tutorial_en.md | 10 ++++++++++ doc/full_tutorial_ru.md | 9 +++++++++ 3 files changed, 27 insertions(+) diff --git a/cherrypick/README.md b/cherrypick/README.md index 24664e9..1bb4e54 100644 --- a/cherrypick/README.md +++ b/cherrypick/README.md @@ -387,6 +387,14 @@ try { **More details:** See [cycle_detection.en.md](doc/cycle_detection.en.md) + +## FAQ + +### Q: Do I need to use `await` with CherryPick.closeRootScope(), scope.closeScope(), or scope.dispose() if I have no Disposable services? + +**A:** +Yes! Even if none of your services currently implement `Disposable`, always use `await` when closing scopes. If you later add resource cleanup (by implementing `dispose()`), CherryPick will handle it automatically without you needing to change your scope cleanup code. This ensures resource management is future-proof, robust, and covers all application scenarios. + ## Documentation - [Circular Dependency Detection (English)](doc/cycle_detection.en.md) diff --git a/doc/full_tutorial_en.md b/doc/full_tutorial_en.md index ac2fca4..f30e7e0 100644 --- a/doc/full_tutorial_en.md +++ b/doc/full_tutorial_en.md @@ -460,6 +460,16 @@ You can use CherryPick in Dart CLI, server apps, and microservices. All major fe | `@inject` | Auto-injection | Class fields | | `@scope` | Scope/realm | Class fields | + +--- + +## FAQ + +### Q: Do I need to use `await` with CherryPick.closeRootScope(), scope.closeScope(), or scope.dispose() if I have no Disposable services? + +**A:** +Yes! Even if none of your services currently implement `Disposable`, always use `await` when closing scopes. If you later add resource cleanup (by implementing `dispose()`), CherryPick will handle it automatically without you needing to change your scope cleanup code. This ensures resource management is future-proof, robust, and covers all application scenarios. + --- ## Useful Links diff --git a/doc/full_tutorial_ru.md b/doc/full_tutorial_ru.md index 13c20f6..21df6c8 100644 --- a/doc/full_tutorial_ru.md +++ b/doc/full_tutorial_ru.md @@ -465,6 +465,15 @@ void main() { --- +## FAQ + +### В: Нужно ли использовать `await` для CherryPick.closeRootScope(), scope.closeScope() или scope.dispose(), если ни один сервис не реализует Disposable? + +**О:** +Да! Даже если в данный момент ни один сервис не реализует Disposable, всегда используйте `await` при закрытии скоупа. Если в будущем потребуется добавить освобождение ресурсов через dispose, CherryPick вызовет его автоматически без изменения завершения работы ваших скоупов. Такой подход делает управление ресурсами устойчивым и безопасным для любых изменений архитектуры. + +--- + ## Полезные ссылки - [cherrypick](https://pub.dev/packages/cherrypick)