From 01d82e1cd30036356f7ccc6ef7f0c364364e7fde Mon Sep 17 00:00:00 2001
From: Sergey Penkovsky <sergey.penkovsky@gmail.com>
Date: Wed, 6 Aug 2025 22:53:33 +0300
Subject: [PATCH] feat(report): add legend to MarkdownReport output with
 explanation of columns

---
 benchmark_cherrypick/README.md                | 11 ++++++++++
 .../lib/cli/benchmark_cli.dart                | 12 +++++------
 .../lib/cli/report/markdown_report.dart       | 21 ++++++++++++++++---
 3 files changed, 35 insertions(+), 9 deletions(-)

diff --git a/benchmark_cherrypick/README.md b/benchmark_cherrypick/README.md
index 629e0ce..2b739ac 100644
--- a/benchmark_cherrypick/README.md
+++ b/benchmark_cherrypick/README.md
@@ -89,6 +89,17 @@ class MyBenchmark extends BenchmarkBase with BenchmarkWithScope {
 
 ---
 
+| Benchmark         | Chain Count | Depth | Mean (us) | Median | Stddev | Min   | Max   | N | ΔRSS(KB) | ΔPeak(KB) | PeakRSS(KB) |
+| ----------------- | ----------- | ----- | --------- | ------ | ------ | ----- | ----- | - | -------- | --------- | ----------- |
+| RegisterSingleton | 10          | 5     | 23.00     | 44.00  | 21.00  | 2.00  | 44.00 | 2 | 16       | 16        | 200400      |
+| ChainSingleton    | 10          | 5     | 42.50     | 51.00  | 8.50   | 34.00 | 51.00 | 2 | 64       | 64        | 200592      |
+| ChainFactory      | 10          | 5     | 42.00     | 48.00  | 6.00   | 36.00 | 48.00 | 2 | 64       | 64        | 200688      |
+| AsyncChain        | 10          | 5     | 49.00     | 52.00  | 3.00   | 46.00 | 52.00 | 2 | 0        | 0         | 200784      |
+| Named             | 10          | 5     | 1.00      | 1.00   | 0.00   | 1.00  | 1.00  | 2 | 0        | 0         | 200784      |
+| Override          | 10          | 5     | 1.50      | 2.00   | 0.50   | 1.00  | 2.00  | 2 | 0        | 0         | 200800      |
+
+---
+
 ## License
 
 MIT
diff --git a/benchmark_cherrypick/lib/cli/benchmark_cli.dart b/benchmark_cherrypick/lib/cli/benchmark_cli.dart
index 83d2485..9b155d8 100644
--- a/benchmark_cherrypick/lib/cli/benchmark_cli.dart
+++ b/benchmark_cherrypick/lib/cli/benchmark_cli.dart
@@ -54,13 +54,13 @@ class BenchmarkCliRunner {
             'benchmark': 'Universal_$bench',
             'chainCount': c,
             'nestingDepth': d,
-            'mean_us': mean.round(),
-            'median_us': median.round(),
-            'stddev_us': stddev.round(),
-            'min_us': minVal.round(),
-            'max_us': maxVal.round(),
+            'mean_us': mean.toStringAsFixed(2),
+            'median_us': median.toStringAsFixed(2),
+            'stddev_us': stddev.toStringAsFixed(2),
+            'min_us': minVal.toStringAsFixed(2),
+            'max_us': maxVal.toStringAsFixed(2),
             'trials': timings.length,
-            'timings_us': timings.map((t) => t.round()).toList(),
+            'timings_us': timings.map((t) => t.toStringAsFixed(2)).toList(),
             'memory_diff_kb': benchResult.memoryDiffKb,
             'delta_peak_kb': benchResult.deltaPeakKb,
             'peak_rss_kb': benchResult.peakRssKb,
diff --git a/benchmark_cherrypick/lib/cli/report/markdown_report.dart b/benchmark_cherrypick/lib/cli/report/markdown_report.dart
index 38e7c37..5e58f66 100644
--- a/benchmark_cherrypick/lib/cli/report/markdown_report.dart
+++ b/benchmark_cherrypick/lib/cli/report/markdown_report.dart
@@ -45,12 +45,27 @@ class MarkdownReport extends ReportGenerator {
     });
 
     String rowToLine(List<String> row, {String sep = ' | '}) =>
-        '| ' + List.generate(row.length, (i) => row[i].padRight(widths[i])).join(sep) + ' |';
+        '| ${List.generate(row.length, (i) => row[i].padRight(widths[i])).join(sep)} |';
 
     final headerLine = rowToLine(headers);
-    final divider = '| ' + widths.map((w) => '-' * w).join(' | ') + ' |';
+    final divider = '| ${widths.map((w) => '-' * w).join(' | ')} |';
     final lines = dataRows.map(rowToLine).toList();
 
-    return ([headerLine, divider] + lines).join('\n');
+    final legend = '''
+      > **Legend:**  
+      > `Benchmark` – Test name  
+      > `Chain Count` – Number of independent chains  
+      > `Depth` – Depth of each chain  
+      > `Mean (us)` – Average time per run (microseconds)  
+      > `Median` – Median time per run  
+      > `Stddev` – Standard deviation  
+      > `Min`, `Max` – Min/max run time  
+      > `N` – Number of measurements  
+      > `ΔRSS(KB)` – Change in process memory (KB)  
+      > `ΔPeak(KB)` – Change in peak RSS (KB)  
+      > `PeakRSS(KB)` – Max observed RSS memory (KB)  
+      ''';
+
+    return '$legend\n\n${([headerLine, divider] + lines).join('\n')}' ;
   }
 }
\ No newline at end of file