doc(README) update content

CHANGELOG.md

@@ -18,12 +18,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   [168](https://github.com/dartoos-dev/json_cache/issues/168).
 
 - Update linting rules —
-  [162](https://github.com/dartoos-dev/json_cache/issues/154).
+  [162](https://github.com/dartoos-dev/json_cache/issues/162).
+
+- Update README — [167](https://github.com/dartoos-dev/json_cache/issues/167).
 
 ### Fixed
 
 - Mehtod `keys` returns an immutable copy of the underlying cache keys —
-  [165](https://github.com/dartoos-dev/json_cache/issues/152)
+  [165](https://github.com/dartoos-dev/json_cache/issues/165).
 
 ## [3.0.2] - 2024-08-19
 

README.md

@@ -72,12 +72,12 @@ that can be selected and grouped in various combinations to meet specific cache
 requirements.
 
 [JsonCache](https://pub.dev/documentation/json_cache/latest/json_cache/JsonCache-class.html)
-is the core interface of this package and represents the concept of cached data.
-It is defined as:
+is the core Dart interface of this package and represents the concept of cached
+data. It is defined as:
 
 ```dart
 /// Represents cached data in json format.
-abstract class JsonCache {
+abstract interface class JsonCache {
   /// Frees up storage space — deletes all keys and values.
   Future<void> clear();
 
@@ -97,6 +97,11 @@ abstract class JsonCache {
   ///
   /// Returns `true` if there is cached data at [key]; `false` otherwise.
   Future<bool> contains(String key);
+
+  /// The cache keys.
+  ///
+  /// Returns an **unmodifiable** list of all cache keys without duplicates.
+  Future<UnmodifiableListView<String>> keys();
 }
 ```
 
@@ -281,9 +286,14 @@ is an implementation on top of the
 [localstorage](https://pub.dev/packages/localstorage) package.
 
 ```dart
+import 'package:flutter/material.dart';
+import 'package:localstorage/localstorage.dart';
+
   …
   final LocalStorage storage = LocalStorage('my_data');
-  final JsonCache jsonCache = JsonCacheMem(JsonCacheLocalStorage(storage));
+  WidgetsFlutterBinding.ensureInitialized();
+  await initLocalStorage();
+  final JsonCache jsonCache = JsonCacheMem(JsonCacheLocalStorage(localStorage));
   …
 ```
 

lib/src/json_cache_hollow.dart

@@ -2,21 +2,28 @@ import 'dart:collection';
 
 import 'package:json_cache/json_cache.dart';
 
-/// Hollow (empty) [JsonCache] — It is intended to serve as a placeholder for
+/// {@template json_cache_hollow}
+///
+/// Hollow [JsonCache] — It is intended to serve as a placeholder for
 /// [JsonCache] instances.
 ///
 /// There will always be at most one [JsonCacheHollow] object in memory during
 /// program execution. It doesn't matter how many times someone instantiates
 /// objects using `const JsonCacheHollow()`.
 ///
-/// > hollow
+/// > hollow:
+/// >
+/// >    having a hole or empty space inside:
+/// >    - a hollow tube
+/// >    - Hollow blocks are used because they are lighter
+/// >    - a hollow log
 /// >
-/// > having a hole or empty space inside:
-/// > - a hollow tube
-/// > - Hollow blocks are used because they are lighter
-/// > - a hollow log
 /// > — [Cambridge Dictionary](https://dictionary.cambridge.org/dictionary/english/hollow)
+///
+/// {@endtemplate}
 final class JsonCacheHollow implements JsonCache {
+  /// {@macro json_cache_hollow}
+  ///
   /// This const constructor ensures that there will be only one
   /// [JsonCacheHollow] instance throughout the program.
   const JsonCacheHollow();