From adf13f3ea0170a7efee2dc111e9c7a2925ebfc6d Mon Sep 17 00:00:00 2001
From: JaffaKetchup <github@jaffaketchup.dev>
Date: Sun, 24 Mar 2024 21:41:18 +0000
Subject: [PATCH] Minor documentation improvements

---
 lib/src/backend/impls/objectbox/backend/internal.dart |  4 ++++
 lib/src/backend/interfaces/backend/internal.dart      | 11 +++++------
 lib/src/root/statistics.dart                          |  2 ++
 lib/src/store/statistics.dart                         |  2 +-
 4 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/lib/src/backend/impls/objectbox/backend/internal.dart b/lib/src/backend/impls/objectbox/backend/internal.dart
index 0c35c8b1..93ad96eb 100644
--- a/lib/src/backend/impls/objectbox/backend/internal.dart
+++ b/lib/src/backend/impls/objectbox/backend/internal.dart
@@ -5,6 +5,8 @@ part of 'backend.dart';
 
 /// Internal implementation of [FMTCBackend] that uses ObjectBox as the storage
 /// database
+///
+/// Actual implementation performed by `_worker` via `_ObjectBoxBackendImpl`.
 abstract interface class FMTCObjectBoxBackendInternal
     implements FMTCBackendInternal {
   static final _instance = _ObjectBoxBackendImpl._();
@@ -84,6 +86,8 @@ class _ObjectBoxBackendImpl implements FMTCObjectBoxBackendInternal {
 
     try {
       // Not using yield* as it doesn't allow for correct error handling
+      // (because result must be 'evaluated' here, instead of a direct
+      // passthrough)
       await for (final evt in controller.stream) {
         // Listen to responses
         yield evt;
diff --git a/lib/src/backend/interfaces/backend/internal.dart b/lib/src/backend/interfaces/backend/internal.dart
index b490f464..8f609945 100644
--- a/lib/src/backend/interfaces/backend/internal.dart
+++ b/lib/src/backend/interfaces/backend/internal.dart
@@ -219,8 +219,8 @@ abstract interface class FMTCBackendInternal
   /// {@template fmtc.backend.setMetadata}
   /// Set a key-value pair in the metadata for the specified store
   ///
-  /// Note that this operation will override the stored value if there is already
-  /// a matching key present.
+  /// Note that this operation will overwrite any existing value for the
+  /// specified key.
   ///
   /// Prefer using [setBulkMetadata] when setting multiple keys. Only one backend
   /// operation is required to set them all at once, and so is more efficient.
@@ -234,8 +234,8 @@ abstract interface class FMTCBackendInternal
   /// {@template fmtc.backend.setBulkMetadata}
   /// Set multiple key-value pairs in the metadata for the specified store
   ///
-  /// Note that this operation will override the stored value if there is already
-  /// a matching key present.
+  /// Note that this operation will overwrite any existing value for each
+  /// specified key.
   /// {@endtemplate}
   Future<void> setBulkMetadata({
     required String storeName,
@@ -304,8 +304,7 @@ abstract interface class FMTCBackendInternal
   });
 
   /// {@template fmtc.backend.watchStores}
-  /// Watch for changes in the specified stores, or all stores if no stores
-  /// are provided
+  /// Watch for changes in the specified stores
   ///
   /// Useful to update UI only when required, for example, in a `StreamBuilder`.
   /// Whenever this has an event, it is likely the other statistics will have
diff --git a/lib/src/root/statistics.dart b/lib/src/root/statistics.dart
index e0ca29ed..fb668bb8 100644
--- a/lib/src/root/statistics.dart
+++ b/lib/src/root/statistics.dart
@@ -33,6 +33,8 @@ class RootStats {
   }
 
   /// {@macro fmtc.backend.watchStores}
+  ///
+  /// If [storeNames] is empty, changes will be watched in all stores.
   Stream<void> watchStores({
     List<String> storeNames = const [],
     bool triggerImmediately = false,
diff --git a/lib/src/store/statistics.dart b/lib/src/store/statistics.dart
index 8599b294..a8d4117d 100644
--- a/lib/src/store/statistics.dart
+++ b/lib/src/store/statistics.dart
@@ -41,7 +41,7 @@ class StoreStats {
   /// {@macro fmtc.frontend.storestats.efficiency}
   Future<int> get hits => all.then((a) => a.hits);
 
-  /// Retrieve number of unsuccessful tile retrievals when browsing
+  /// Retrieve the number of unsuccessful tile retrievals when browsing
   ///
   /// {@macro fmtc.frontend.storestats.efficiency}
   Future<int> get misses => all.then((a) => a.misses);