From b84a3e8b44f8bf025cf0cb3001746a86aa0dd260 Mon Sep 17 00:00:00 2001
From: Moudy <m.ellaz@hotmail.com>
Date: Mon, 18 May 2026 16:37:11 +0200
Subject: [PATCH] docs(cycle_bench): document Stats fields and use Display
 instead of ::format()

- Add /// doc comments on Stats {n, best_ms, mean_ms, stdev_ms}
  clarifying units, semantics, and Bessel's correction.
- Replace pub fn format(&self) -> String with impl fmt::Display for
  Stats, idiomatic and lets println! use {} directly.
- Update three call sites accordingly.
---
 tools/cycle_bench/src/main.rs  |  8 ++------
 tools/cycle_bench/src/ppe.rs   |  2 +-
 tools/cycle_bench/src/stats.rs | 16 +++++++++++++---
 3 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/tools/cycle_bench/src/main.rs b/tools/cycle_bench/src/main.rs
index 6f254868..d002d566 100644
--- a/tools/cycle_bench/src/main.rs
+++ b/tools/cycle_bench/src/main.rs
@@ -581,7 +581,7 @@ fn print_table(results: &[BenchResult], prove: bool) {
     let sw = 8_usize;
     let exec_w = results
         .iter()
-        .map(|r| r.exec_stats.format().len())
+        .map(|r| r.exec_stats.to_string().len())
         .max()
         .unwrap_or(0)
         .max("exec_ms (best / mean ± stdev)".len());
@@ -594,11 +594,7 @@ fn print_table(results: &[BenchResult], prove: bool) {
     for r in results {
         println!(
             "{:<pw$}  {:<iw$}  {:>cw$}  {:>sw$}  {:<exec_w$}",
-            r.program,
-            r.instruction,
-            r.user_cycles,
-            r.segments,
-            r.exec_stats.format(),
+            r.program, r.instruction, r.user_cycles, r.segments, r.exec_stats,
         );
     }
 
diff --git a/tools/cycle_bench/src/ppe.rs b/tools/cycle_bench/src/ppe.rs
index 0390f533..e3bc4747 100644
--- a/tools/cycle_bench/src/ppe.rs
+++ b/tools/cycle_bench/src/ppe.rs
@@ -118,5 +118,5 @@ pub fn print_verify(r: &VerifyBenchResult) {
         r.proof_bytes
     );
     println!("  journal_bytes : {}", r.journal_bytes);
-    println!("  verify_ms     : {}", r.stats.format());
+    println!("  verify_ms     : {}", r.stats);
 }
diff --git a/tools/cycle_bench/src/stats.rs b/tools/cycle_bench/src/stats.rs
index b1e45b56..7f75fd6f 100644
--- a/tools/cycle_bench/src/stats.rs
+++ b/tools/cycle_bench/src/stats.rs
@@ -4,13 +4,20 @@
 //! bench READMEs print) and mean +/- stdev (the figure the fee model wants, since
 //! it cares about the steady-state cost not a single fastest sample).
 
+use std::fmt;
+
 use serde::Serialize;
 
 #[derive(Debug, Serialize, Clone, Copy, Default)]
 pub struct Stats {
+    /// Number of samples in the aggregate (excluding warmup).
     pub n: usize,
+    /// Lowest sample (ms). Strips OS jitter; matches the bench README "best of N" figure.
     pub best_ms: f64,
+    /// Arithmetic mean of samples (ms).
     pub mean_ms: f64,
+    /// Sample standard deviation of samples (ms), computed with Bessel's correction (n-1).
+    /// 0.0 when n < 2.
     pub stdev_ms: f64,
 }
 
@@ -43,10 +50,13 @@ impl Stats {
             stdev_ms,
         }
     }
+}
 
-    /// Format as `best / mean ± stdev (n=N)` for table display.
-    pub fn format(&self) -> String {
-        format!(
+/// `best / mean ± stdev (n=N)` for table display.
+impl fmt::Display for Stats {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
             "{:.2} / {:.2} ± {:.2} (n={})",
             self.best_ms, self.mean_ms, self.stdev_ms, self.n,
         )