Minor tweaks in Finalizer documentation:
- Fix typos in "Get finalizer callback" -> "Call finalizer callback"
in documentation of an `attach` call.
- Make it clear that the `detach` parameter of `attach` is not used by
the finalizer.
- Make it clear what "the same value" means in the `detach` parameter
documentation.
CoreLibraryReviewExempt: Documentation only
Change-Id: I8c1dc9e5fd6926e5c594c26a50228a044e892974
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/364100
Reviewed-by: Lasse Nielsen <lrn@google.com>
Commit-Queue: Ömer Ağacan <omersa@google.com>
diff --git a/sdk/lib/core/weak.dart b/sdk/lib/core/weak.dart
index 0c74cd9..d08d76b 100644
--- a/sdk/lib/core/weak.dart
+++ b/sdk/lib/core/weak.dart
@@ -168,7 +168,7 @@
/// // *and* closes connection if the user forgets to.
/// final connection = DBConnection.connect();
/// final wrapper = Database._fromConnection(connection);
-/// // Get finalizer callback when `wrapper` is no longer reachable.
+/// // Calls finalizer callback when `wrapper` is no longer reachable.
/// _finalizer.attach(wrapper, connection, detach: wrapper);
/// return wrapper;
/// }
@@ -236,8 +236,11 @@
/// The callback may be called at most once per active attachment,
/// ones which have not been detached by calling [Finalizer.detach].
///
- /// If a non-`null` [detach] value is provided, that object can be
- /// passed to [Finalizer.detach] to remove the attachment again.
+ /// The [detach] value is only used by the finalizer to identify the current
+ /// attachment. If a non-`null` [detach] value is provided, the same
+ /// (identical) value can be passed to [Finalizer.detach] to remove the
+ /// attachment. If no (non-`null`) value is provided, the attachment cannot
+ /// be removed again.
///
/// The [value] and [detach] arguments do not count towards those
/// objects being accessible to the program.
@@ -257,7 +260,7 @@
/// // *and* closes connection if the user forgets to.
/// final connection = DBConnection.connect();
/// final wrapper = Database._fromConnection();
- /// // Get finalizer callback when `wrapper` is no longer reachable.
+ /// // Calls finalizer callback when `wrapper` is no longer reachable.
/// _finalizer.attach(wrapper, connection, detach: wrapper);
/// return wrapper;
/// }
