From c0ad44b8bc658b4c16012f9a84d25fe6164334dc Mon Sep 17 00:00:00 2001
From: Craig Labenz <craig.labenz@gmail.com>
Date: Sun, 9 Jul 2023 10:17:30 +0200
Subject: [PATCH 1/2] add hierarchical example and explanation to readme

---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/README.md b/README.md
index 5b96de1..6fb9e28 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,56 @@ Available logging methods are:
 + `log.finer(logged_content);`
 + `log.finest(logged_content);`
 
+## Configuration
+
+Loggers can be individually configured and listened to. When an individual logger has no
+specific configuration, it uses the configuration and any listeners found at `Logger.root`.
+
+To begin, set the global boolean `hierarchicalLoggingEnabled` to `true`.
+
+Then, create unique loggers and configure their `level` attributes and assign any listeners to
+their `onRecord` streams.
+
+
+```dart
+hierarchicalLoggingEnabled = true;
+
+Logger.root.level = Level.FINE;
+
+final log1 = Logger('WARNING+');
+log1.level = Level.WARNING;
+Logger.root.onRecord.listen((record) {
+  print('[WARNING+] ${record.message}');
+});
+
+final log2 = Logger('FINE+'); // Inherited from `Logger.root`
+log2.onRecord.listen((record) {
+  print('[FINE+]    ${record.message}');
+});
+
+log1.info('Will not print because too low level');
+log2.info(
+  'WILL print TWICE ([FINE+] and [WARNING+]) '
+  'because `log2` uses individual and root listeners',
+);
+
+log1.warning('WILL print ONCE because `log1` only uses root listener');
+log2.warning(
+  'WILL print TWICE because `log2` '
+  'uses individual and root listeners',
+);
+```
+
+Results in:
+
+```
+[FINE+]    WILL print TWICE ([FINE+] and [WARNING+]) because `log2` uses individual and root listeners
+[WARNING+] WILL print TWICE ([FINE+] and [WARNING+]) because `log2` uses individual and root listeners
+[WARNING+] WILL print ONCE because `log1` only uses root listener
+[FINE+]    WILL print TWICE because `log2` uses individual and root listeners
+[WARNING+] WILL print TWICE because `log2` uses individual and root listeners
+```
+
 ## Publishing automation
 
 For information about our publishing automation and release process, see

From b1e3453ac874f543a68490fe734efa51608cddf2 Mon Sep 17 00:00:00 2001
From: Craig Labenz <craig.labenz@gmail.com>
Date: Sun, 9 Jul 2023 10:48:36 +0200
Subject: [PATCH 2/2] updates new readme entry for (hopefully) more clarity

---
 README.md | 67 +++++++++++++++++++++++++++++++++----------------------
 1 file changed, 40 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 6fb9e28..70f1660 100644
--- a/README.md
+++ b/README.md
@@ -89,42 +89,55 @@ their `onRecord` streams.
 
 
 ```dart
-hierarchicalLoggingEnabled = true;
+  hierarchicalLoggingEnabled = true;
+  Logger.root.level = Level.WARNING;
+  Logger.root.onRecord.listen((record) {
+    print('[ROOT][WARNING+] ${record.message}');
+  });
 
-Logger.root.level = Level.FINE;
+  final log1 = Logger('FINE+');
+  log1.level = Level.FINE;
+  log1.onRecord.listen((record) {
+    print('[LOG1][FINE+] ${record.message}');
+  });
 
-final log1 = Logger('WARNING+');
-log1.level = Level.WARNING;
-Logger.root.onRecord.listen((record) {
-  print('[WARNING+] ${record.message}');
-});
+  // log2 inherits LEVEL value of WARNING from `Logger.root`
+  final log2 = Logger('WARNING+');
+  log2.onRecord.listen((record) {
+    print('[LOG2][WARNING+] ${record.message}');
+  });
 
-final log2 = Logger('FINE+'); // Inherited from `Logger.root`
-log2.onRecord.listen((record) {
-  print('[FINE+]    ${record.message}');
-});
 
-log1.info('Will not print because too low level');
-log2.info(
-  'WILL print TWICE ([FINE+] and [WARNING+]) '
-  'because `log2` uses individual and root listeners',
-);
-
-log1.warning('WILL print ONCE because `log1` only uses root listener');
-log2.warning(
-  'WILL print TWICE because `log2` '
-  'uses individual and root listeners',
-);
+  // Will NOT print because FINER is too low level for `Logger.root`.
+  log1.finer('LOG_01 FINER (X)');
+
+  // Will print twice ([LOG1] & [ROOT])
+  log1.fine('LOG_01 FINE (√√)');
+
+  // Will print ONCE because `log1` only uses root listener.
+  log1.warning('LOG_01 WARNING (√)');
+
+  // Will never print because FINE is too low level.
+  log2.fine('LOG_02 FINE (X)');
+
+  // Will print twice ([LOG2] & [ROOT]) because warning is sufficient for all
+  // loggers' levels.
+  log2.warning('LOG_02 WARNING (√√)');
+
+  // Will never print because `info` is filtered by `Logger.root.level` of
+  // `Level.WARNING`.
+  log2.info('INFO (X)');
 ```
 
 Results in:
 
 ```
-[FINE+]    WILL print TWICE ([FINE+] and [WARNING+]) because `log2` uses individual and root listeners
-[WARNING+] WILL print TWICE ([FINE+] and [WARNING+]) because `log2` uses individual and root listeners
-[WARNING+] WILL print ONCE because `log1` only uses root listener
-[FINE+]    WILL print TWICE because `log2` uses individual and root listeners
-[WARNING+] WILL print TWICE because `log2` uses individual and root listeners
+[LOG1][FINE+] LOG_01 FINE (√√)
+[ROOT][WARNING+] LOG_01 FINE (√√)
+[LOG1][FINE+] LOG_01 WARNING (√)
+[ROOT][WARNING+] LOG_01 WARNING (√)
+[LOG2][WARNING+] LOG_02 WARNING (√√)
+[ROOT][WARNING+] LOG_02 WARNING (√√)
 ```
 
 ## Publishing automation