doc: documentation improvements

* chore: fix minor typos

* doc(README): tips for storing simple values

Author: rafamizes

README.md

@@ -23,13 +23,14 @@ Rultor.com](https://www.rultor.com/b/dartoos-dev/json_cache)](https://www.rultor
 
 - [Overview](#overview)
 - [Getting Started](#getting-started)
+  - [Storing Simple Values](#storing-simple-values)
   - [Suggested Dependency Relationship](#suggested-dependency-relationship)
 - [Implementations](#implementations)
   - [JsonCacheMem — Thread-safe In-memory cache](#jsoncachemem)
   - [JsonCachePrefs — SharedPreferences](#jsoncacheprefs)
   - [JsonCacheEncPrefs — EncryptedSharedPreferences](#jsoncacheencprefs)
-  - [JsonCacheSecStorage — FlutterSecureStorage](#jsoncachesecstorage)
   - [JsonCacheLocalStorage — LocalStorage](#jsoncachelocalstorage)
+  - [JsonCacheSecStorage — FlutterSecureStorage](#jsoncachesecstorage)
   - [JsonCacheCrossLocalStorage — CrossLocalStorage](#jsoncachecrosslocalstorage)
   - [JsonCacheHive — Hive](#jsoncachehive)
 - [Unit Test Tips](#unit-test-tips)
@@ -77,13 +78,13 @@ It is defined as:
 ```dart
 /// Represents cached data in json format.
 abstract class JsonCache {
-  /// Frees up storage space — deletes all keys with associated values.
+  /// Frees up storage space — deletes all keys and values.
   Future<void> clear();
 
   /// Removes cached data located at [key].
   Future<void> remove(String key);
 
-  /// Retrieves cached data located at [key] or null if a cache miss occurs.
+  /// Retrieves cached data located at [key] or `null` if a cache miss occurs.
   Future<Map<String, dynamic>?> value(String key);
 
   /// It either updates data located at [key] with [value] or, if there is no
@@ -92,7 +93,7 @@ abstract class JsonCache {
   /// **Note**: [value] must be json encodable.
   Future<void> refresh(String key, Map<String, dynamic> value);
 
-  /// Checks whether there is cached data at [key].
+  /// Checks for cached data located at [key].
   ///
   /// Returns `true` if there is cached data at [key]; `false` otherwise.
   Future<bool> contains(String key);
@@ -119,6 +120,25 @@ final JsonCache jsonCache = … retrieve one of the JsonCache implementations.
 await jsonCache.refresh('profile', {'name': 'John Doe', 'email': '[email protected]', 'accountType': 'premium'});
 await jsonCache.refresh('preferences', {'theme': {'dark': true}, 'notifications':{'enabled': true}});
 ```
+### Storing Simple Values
+
+In order to store a simple value such as a `string`, `int`, `double`, etc,
+define it as a **map key** whose associated value is a boolean placeholder value
+set to `true`. For example:
+
+```dart
+  /// Storing a simple text information.
+  jsonCache.refresh('info', {'an important information': true});
+
+  // later on…
+
+  // This variable is a Map containing a single key.
+  final cachedInfo = await memCache.value('info');
+  // The key itself is the content of the stored information.
+  final info = cachedInfo?.keys.first;
+  print(info); // 'an important information'
+
+```
 
 ### Suggested Dependency Relationship
 
@@ -243,6 +263,19 @@ package.
   final JsonCache jsonCache = JsonCacheMem(JsonCacheEncPrefs(encPrefs));
   …
 ```
+### JsonCacheLocalStorage
+
+[JsonCacheLocalStorage](https://pub.dev/documentation/json_cache/latest/json_cache/JsonCacheLocalStorage-class.html)
+is an implementation on top of the
+[localstorage](https://pub.dev/packages/localstorage) package.
+
+```dart
+  …
+  final LocalStorage storage = LocalStorage('my_data');
+  final JsonCache jsonCache = JsonCacheMem(JsonCacheLocalStorage(storage));
+  …
+```
+
 
 ### JsonCacheSecStorage
 
@@ -256,26 +289,12 @@ is an implementation on top of the
   final JsonCache jsonCache = JsonCacheSecStorage(secStorage);
   // In order to write a string value, define it as a map key whose associated
   // value is a boolean placeholder value set to 'true'.
-  final Map<String, dynamic> info = {'an secret info': true};
-  jsonCache.refresh('secret', info);
+  jsonCache.refresh('secret', {'a secret info': true});
 
   // later on…
 
-  final mappedInfo = (await jsonCache.value('secret'))!;
-  final originalInfo = mappedInfo.keys.first; // 'an secret info'
-```
-
-### JsonCacheLocalStorage
-
-[JsonCacheLocalStorage](https://pub.dev/documentation/json_cache/latest/json_cache/JsonCacheLocalStorage-class.html)
-is an implementation on top of the
-[localstorage](https://pub.dev/packages/localstorage) package.
-
-```dart
-  …
-  final LocalStorage storage = LocalStorage('my_data');
-  final JsonCache jsonCache = JsonCacheMem(JsonCacheLocalStorage(storage));
-  …
+  final cachedInfo = await jsonCache.value('secret');
+  final info = cachedInfo?.keys.first; // 'a secret info'
 ```
 
 ### JsonCacheCrossLocalStorage

analysis_options.yaml

@@ -6,7 +6,7 @@ analyzer:
     implicit-casts: false
     # A value of false ensures that the type inference engine never chooses the
     # dynamic type when it can’t determine a static type.
-    implicit-dynamic: false
+    # implicit-dynamic: false
 linter:
   rules:
     # Make constructors the first thing in every class

lib/src/json_cache.dart

@@ -6,13 +6,13 @@
 ///> elsewhere.
 ///> — [cache Wikipedia](https://en.wikipedia.org/wiki/Cache_(computing))
 abstract class JsonCache {
-  /// Frees up storage space — deletes all keys with associated values.
+  /// Frees up storage space — deletes all keys and values.
   Future<void> clear();
 
   /// Removes cached data located at [key].
   Future<void> remove(String key);
 
-  /// Retrieves cached data located at [key] or null if a cache miss occurs.
+  /// Retrieves cached data located at [key] or `null` if a cache miss occurs.
   Future<Map<String, dynamic>?> value(String key);
 
   /// It either updates the data found at [key] with [value] or, if there is no
@@ -21,7 +21,7 @@ abstract class JsonCache {
   /// **Note**: [value] must be json encodable.
   Future<void> refresh(String key, Map<String, dynamic> value);
 
-  /// Checks whether there is cached data at [key].
+  /// Checks for cached data located at [key].
   ///
   /// Returns `true` if there is cached data at [key]; `false` otherwise.
   Future<bool> contains(String key);