From 4d872d7c255efa94721c5029fd33103e56477f80 Mon Sep 17 00:00:00 2001
From: Sergey Penkovsky <sergey.penkovsky@gmail.com>
Date: Mon, 11 Aug 2025 11:53:25 +0300
Subject: [PATCH] docs(disposable): add detailed English documentation and
 usage examples for Disposable interface; chore: update binding_resolver and
 add explanatory comment in scope_test for deprecated usage.\n\n- Expanded
 Disposable interface docs, added sync & async example classes, and CherryPick
 integration sample.\n- Clarified how to implement and use Disposable in DI
 context.\n- Updated binding_resolver for internal improvements.\n- Added
 ignore for deprecated member use in scope_test for clarity and future
 upgrades.\n\nBREAKING CHANGE: Documentation style enhancement and clearer API
 usage for Disposable implementations.

---
 cherrypick/lib/src/binding_resolver.dart | 13 +++++
 cherrypick/lib/src/disposable.dart       | 61 ++++++++++++++++++++++--
 cherrypick/test/src/scope_test.dart      |  1 +
 3 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/cherrypick/lib/src/binding_resolver.dart b/cherrypick/lib/src/binding_resolver.dart
index 37c196b..708ec1d 100644
--- a/cherrypick/lib/src/binding_resolver.dart
+++ b/cherrypick/lib/src/binding_resolver.dart
@@ -1,3 +1,16 @@
+//
+// Copyright 2021 Sergey Penkovsky (sergey.penkovsky@gmail.com)
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      https://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
 import 'dart:async';
 
 typedef Instance<T> = FutureOr<T>;
diff --git a/cherrypick/lib/src/disposable.dart b/cherrypick/lib/src/disposable.dart
index 37d93ee..cece293 100644
--- a/cherrypick/lib/src/disposable.dart
+++ b/cherrypick/lib/src/disposable.dart
@@ -1,10 +1,63 @@
-/// Базовый интерфейс для автоматического управления ресурсами в CherryPick.
-/// Если объект реализует [Disposable], DI-контейнер вызовет [dispose] при очистке scope.
+//
+// Copyright 2021 Sergey Penkovsky (sergey.penkovsky@gmail.com)
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      https://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
 import 'dart:async';
 
-/// Interface for resources that need to be disposed synchronously or asynchronously.
+/// An interface for resources that require explicit cleanup, used by the CherryPick dependency injection container.
+///
+/// If an object implements [Disposable], the CherryPick DI container will automatically call [dispose]
+/// when the corresponding scope is cleaned up. Use [Disposable] for closing streams, files, controllers, services, etc.
+/// Both synchronous and asynchronous cleanup is supported:
+/// - For sync disposables, implement [dispose] as a `void` or simply return nothing.
+/// - For async disposables, implement [dispose] returning a [Future].
+///
+/// Example: Synchronous Disposable
+/// ```dart
+/// class MyLogger implements Disposable {
+///   void dispose() {
+///     print('Logger closed!');
+///   }
+/// }
+/// ```
+///
+/// Example: Asynchronous Disposable
+/// ```dart
+/// class MyConnection implements Disposable {
+///   @override
+///   Future<void> dispose() async {
+///     await connection.close();
+///   }
+/// }
+/// ```
+///
+/// Usage with CherryPick DI Module
+/// ```dart
+/// final scope = openRootScope();
+/// scope.installModules([
+///   Module((b) {
+///     b.bind<MyLogger>((_) => MyLogger());
+///     b.bindAsync<MyConnection>((_) async => MyConnection());
+///   }),
+/// ]);
+/// // ...
+/// await scope.close(); // will automatically call dispose on all Disposables
+/// ```
+///
+/// This pattern ensures that all resources are released safely and automatically when the scope is destroyed.
 abstract class Disposable {
   /// Releases all resources held by this object.
-  /// For sync disposables, just implement as void; for async ones, return Future.
+  ///
+  /// Implement cleanup logic (closing streams, sockets, files, etc.) within this method.
+  /// Return a [Future] for async cleanup, or nothing (`void`) for synchronous cleanup.
   FutureOr<void> dispose();
 }
diff --git a/cherrypick/test/src/scope_test.dart b/cherrypick/test/src/scope_test.dart
index edb35ea..4d6cdfe 100644
--- a/cherrypick/test/src/scope_test.dart
+++ b/cherrypick/test/src/scope_test.dart
@@ -95,6 +95,7 @@ class AsyncModule extends Module {
   @override
   void builder(Scope scope) {
     bind<AsyncCreatedDisposable>()
+        // ignore: deprecated_member_use_from_same_package
         .toProvideAsync(() async {
           await Future.delayed(Duration(milliseconds: 10));
           return AsyncCreatedDisposable();