Minor documentation improvements

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;

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

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,

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);