docs: enhance benchmark documentation with value construction convention (#118)

- Added a section on value construction convention to the benchmark files, clarifying how benchmark entry points utilize `Fn(u64) -> Arc<V>` for value storage.
- Emphasized the importance of using the cheapest possible payload to focus on cache policy behavior rather than allocator costs.

These updates improve the clarity of benchmark usage and ensure users understand the implications of value construction on performance metrics.

Author: TKorr

benches/reports.rs

@@ -2,6 +2,15 @@
 //!
 //! This is a standalone binary (not a criterion benchmark) that prints
 //! human-readable comparison tables for cache policy evaluation.
+//!
+//! ## Value construction convention
+//!
+//! Benchmark entry points take a `value_for_key: Fn(u64) -> Arc<V>` so callers
+//! choose what to store. We pass [`Arc::new`] directly, which the compiler
+//! resolves to `fn(u64) -> Arc<u64>`, i.e. the value is the key itself wrapped
+//! in `Arc`. Cache-policy measurements (hit/miss, eviction, latency) don't
+//! depend on payload contents, so the cheapest possible payload keeps the
+//! workload focused on policy behavior rather than allocator/clone cost.
 
 use bench_support as common;
 use bench_support::for_each_policy;

benches/runner.rs

@@ -4,6 +4,15 @@
 //! JSON results to `target/benchmarks/<run-id>/results.json`.
 //!
 //! Run with: `cargo bench --bench runner`
+//!
+//! ## Value construction convention
+//!
+//! Benchmark entry points take a `value_for_key: Fn(u64) -> Arc<V>` so callers
+//! choose what to store. We pass [`Arc::new`] directly, which the compiler
+//! resolves to `fn(u64) -> Arc<u64>`, i.e. the value is the key itself wrapped
+//! in `Arc`. Cache-policy measurements (hit/miss, eviction, latency) don't
+//! depend on payload contents, so the cheapest possible payload keeps the
+//! workload focused on policy behavior rather than allocator/clone cost.
 
 use bench_support as common;
 use bench_support::for_each_policy;

benches/workloads.rs

@@ -11,6 +11,15 @@
 //! For micro-ops (get/insert latency), see: `cargo bench --bench ops`
 //! For policy-specific operations, see: `cargo bench --bench policy_*`
 //! For external crate comparison, see: `cargo bench --bench comparison`
+//!
+//! ## Value construction convention
+//!
+//! Benchmark entry points take a `value_for_key: Fn(u64) -> Arc<V>` so callers
+//! choose what to store. We pass [`Arc::new`] directly, which the compiler
+//! resolves to `fn(u64) -> Arc<u64>`, i.e. the value is the key itself wrapped
+//! in `Arc`. Cache-policy measurements (hit/miss, eviction, latency) don't
+//! depend on payload contents, so the cheapest possible payload keeps the
+//! workload focused on policy behavior rather than allocator/clone cost.
 
 use bench_support as common;
 use bench_support::for_each_policy;