Add module-level doc comments to all simulator source files

hxrts · hxrts · commit db0bbbd8b8c5 · 2026-04-17T17:58:22.000+02:00
diff --git a/crates/simulator/src/assertions.rs b/crates/simulator/src/assertions.rs
@@ -1,3 +1,5 @@
+//! Scenario assertion builders and validation helpers for routing outcomes.
+
 use std::{error::Error, fmt};
 
 use jacquard_core::{DestinationId, NodeId, RoutingEngineId};
diff --git a/crates/simulator/src/bin/tuning_matrix.rs b/crates/simulator/src/bin/tuning_matrix.rs
@@ -1,3 +1,5 @@
+//! CLI binary for running tuning and diffusion experiment suites.
+
 use std::{
     env,
     path::{Path, PathBuf},
diff --git a/crates/simulator/src/diffusion/catalog/mod.rs b/crates/simulator/src/diffusion/catalog/mod.rs
@@ -1,3 +1,5 @@
+//! Pre-configured diffusion scenario families and policy parameter variations.
+
 use super::model::{
     DiffusionForwardingStyle, DiffusionPolicyConfig, DiffusionRunSpec, DiffusionScenarioSpec,
     DiffusionSuite,
diff --git a/crates/simulator/src/diffusion/mod.rs b/crates/simulator/src/diffusion/mod.rs
@@ -1,3 +1,5 @@
+//! Diffusion message-delivery simulation with posture, scoring, and statistics.
+
 use std::collections::{BTreeMap, BTreeSet};
 
 mod catalog;
diff --git a/crates/simulator/src/diffusion/model.rs b/crates/simulator/src/diffusion/model.rs
@@ -1,3 +1,5 @@
+//! Diffusion policy config, forwarding styles, field postures, and scenario specs.
+
 use std::{collections::BTreeMap, path::PathBuf};
 
 use serde::{Deserialize, Serialize};
diff --git a/crates/simulator/src/diffusion/posture.rs b/crates/simulator/src/diffusion/posture.rs
@@ -1,3 +1,5 @@
+//! Field posture classification and signal computation for diffusion strategies.
+
 use super::{
     coverage_permille_for, is_target_node, is_terminal_target, node_by_id,
     scenario_target_cluster_count, BTreeMap, BTreeSet, DiffusionContactEvent,
diff --git a/crates/simulator/src/diffusion/runtime/mod.rs b/crates/simulator/src/diffusion/runtime/mod.rs
@@ -1,3 +1,5 @@
+//! Diffusion execution engine with round-level state management and transfer scoring.
+
 use std::{
     collections::{BTreeMap, BTreeSet},
     fs::{self, File},
diff --git a/crates/simulator/src/diffusion/scoring.rs b/crates/simulator/src/diffusion/scoring.rs
@@ -1,3 +1,5 @@
+//! Forwarding score computation for diffusion routing decisions.
+
 use super::{
     diffusion_bridge_candidate, diffusion_destination_cluster, diffusion_source_cluster,
     is_target_node, node_by_id, sender_energy_ratio_permille, DiffusionContactEvent,
diff --git a/crates/simulator/src/diffusion/stats.rs b/crates/simulator/src/diffusion/stats.rs
@@ -1,3 +1,5 @@
+//! Statistical aggregation helpers for diffusion run analysis.
+
 use crate::util::stats::{average_option_u32, average_u32, mode_string as util_mode_string};
 
 pub(super) use crate::util::stats::min_max_spread_u32;
diff --git a/crates/simulator/src/environment.rs b/crates/simulator/src/environment.rs
@@ -1,3 +1,5 @@
+//! Environment hooks: topology changes, degradation, partitions, and mobility events.
+
 use std::collections::BTreeMap;
 
 use jacquard_core::{
diff --git a/crates/simulator/src/experiments/catalog/batman.rs b/crates/simulator/src/experiments/catalog/batman.rs
@@ -1,3 +1,5 @@
+//! Batman-Bellman, Batman-Classic, Babel, and OLSRv2 scenario family definitions.
+
 use super::FamilyDescriptor;
 use crate::experiments::{
     build_babel_asymmetry_cost_penalty, build_babel_decay_window_pressure,
diff --git a/crates/simulator/src/experiments/catalog/comparative.rs b/crates/simulator/src/experiments/catalog/comparative.rs
@@ -1,3 +1,5 @@
+//! Comparative and head-to-head scenario family definitions.
+
 use super::{materialize_families, FamilyBuilder, FamilyDescriptor};
 use crate::experiments::{
     build_comparison_bridge_transition, build_comparison_concurrent_mixed,
diff --git a/crates/simulator/src/harness/build_plan.rs b/crates/simulator/src/harness/build_plan.rs
@@ -1,3 +1,5 @@
+//! Host build plans with engine configuration and bootstrap state management.
+
 use jacquard_core::{Configuration, Observation, Tick};
 use jacquard_mem_link_profile::SharedInMemoryNetwork;
 use jacquard_reference_client::{
diff --git a/crates/simulator/src/harness/mod.rs b/crates/simulator/src/harness/mod.rs
@@ -1,3 +1,5 @@
+//! Deterministic simulator harness orchestrating scenario execution and round advancement.
+
 use std::{collections::BTreeMap, sync::Arc};
 
 use jacquard_core::{
diff --git a/crates/simulator/src/harness/replay_support.rs b/crates/simulator/src/harness/replay_support.rs
@@ -1,3 +1,5 @@
+//! Route event collection, host snapshots, and simulation artifact assembly.
+
 use super::{
     ActiveRouteSummary, BTreeMap, BoundObjective, BridgeRoundProgress, BridgeRoundReport,
     ConnectivityPosture, DestinationId, DriverStatusEvent, DurationMs, FieldExportedReplayBundle,
diff --git a/crates/simulator/src/presets/basics.rs b/crates/simulator/src/presets/basics.rs
@@ -1,3 +1,5 @@
+//! Basic scenario fixtures: line topologies and single-engine host configurations.
+
 #![allow(clippy::wildcard_imports)]
 
 use super::*;
diff --git a/crates/simulator/src/presets/common.rs b/crates/simulator/src/presets/common.rs
@@ -1,3 +1,5 @@
+//! Shared topology builders and parameter helpers for preset scenarios.
+
 #![allow(clippy::wildcard_imports)]
 
 use super::*;
diff --git a/crates/simulator/src/presets/composition.rs b/crates/simulator/src/presets/composition.rs
@@ -1,3 +1,5 @@
+//! Multi-engine routing scenarios for engine composition and coordination testing.
+
 #![allow(clippy::wildcard_imports)]
 
 use super::*;
diff --git a/crates/simulator/src/presets/regressions.rs b/crates/simulator/src/presets/regressions.rs
@@ -1,3 +1,5 @@
+//! Regression test scenarios for churn, relay stability, and edge cases.
+
 #![allow(clippy::wildcard_imports)]
 
 use super::*;
diff --git a/crates/simulator/src/presets/tuning.rs b/crates/simulator/src/presets/tuning.rs
@@ -1,3 +1,5 @@
+//! Parameter tuning scenarios with varied decay windows and search budgets.
+
 #![allow(clippy::wildcard_imports)]
 
 use super::*;
diff --git a/crates/simulator/src/reduced_replay.rs b/crates/simulator/src/reduced_replay.rs
@@ -1,3 +1,5 @@
+//! Condensed replay view: per-route presence, materialization, and loss summaries.
+
 use std::collections::BTreeSet;
 
 use jacquard_core::{DestinationId, NodeId, RouteLifecycleEvent, RoutingEngineId};
diff --git a/crates/simulator/src/replay.rs b/crates/simulator/src/replay.rs
@@ -1,3 +1,5 @@
+//! Simulation replay artifacts: host rounds, route events, checkpoints, and statistics.
+
 use std::collections::BTreeMap;
 
 use jacquard_core::{
diff --git a/crates/simulator/src/scenario.rs b/crates/simulator/src/scenario.rs
@@ -1,3 +1,5 @@
+//! Scenario definition: topology, hosts, objectives, engine lanes, and overrides.
+
 use jacquard_babel::DecayWindow as BabelDecayWindow;
 use jacquard_batman_bellman::DecayWindow;
 use jacquard_batman_classic::DecayWindow as ClassicDecayWindow;
diff --git a/crates/simulator/src/util/mod.rs b/crates/simulator/src/util/mod.rs
@@ -1 +1,3 @@
+//! Shared utility modules for simulation support.
+
 pub(crate) mod stats;
diff --git a/crates/simulator/src/util/stats.rs b/crates/simulator/src/util/stats.rs
@@ -1,3 +1,5 @@
+//! Statistical computation: averages, medians, modes, and ratio calculations.
+
 use std::collections::BTreeMap;
 
 #[must_use]

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! Scenario assertion builders and validation helpers for routing outcomes.`
	`2`	`+`
`1`	`3`	`use std::{error::Error, fmt};`
`2`	`4`
`3`	`5`	`use jacquard_core::{DestinationId, NodeId, RoutingEngineId};`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! CLI binary for running tuning and diffusion experiment suites.`
	`2`	`+`
`1`	`3`	`use std::{`
`2`	`4`	`env,`
`3`	`5`	`path::{Path, PathBuf},`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! Pre-configured diffusion scenario families and policy parameter variations.`
	`2`	`+`
`1`	`3`	`use super::model::{`
`2`	`4`	`DiffusionForwardingStyle, DiffusionPolicyConfig, DiffusionRunSpec, DiffusionScenarioSpec,`
`3`	`5`	`DiffusionSuite,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! Diffusion message-delivery simulation with posture, scoring, and statistics.`
	`2`	`+`
`1`	`3`	`use std::collections::{BTreeMap, BTreeSet};`
`2`	`4`
`3`	`5`	`mod catalog;`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! Diffusion policy config, forwarding styles, field postures, and scenario specs.`
	`2`	`+`
`1`	`3`	`use std::{collections::BTreeMap, path::PathBuf};`
`2`	`4`
`3`	`5`	`use serde::{Deserialize, Serialize};`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! Field posture classification and signal computation for diffusion strategies.`
	`2`	`+`
`1`	`3`	`use super::{`
`2`	`4`	`coverage_permille_for, is_target_node, is_terminal_target, node_by_id,`
`3`	`5`	`scenario_target_cluster_count, BTreeMap, BTreeSet, DiffusionContactEvent,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! Diffusion execution engine with round-level state management and transfer scoring.`
	`2`	`+`
`1`	`3`	`use std::{`
`2`	`4`	`collections::{BTreeMap, BTreeSet},`
`3`	`5`	`fs::{self, File},`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! Forwarding score computation for diffusion routing decisions.`
	`2`	`+`
`1`	`3`	`use super::{`
`2`	`4`	`diffusion_bridge_candidate, diffusion_destination_cluster, diffusion_source_cluster,`
`3`	`5`	`is_target_node, node_by_id, sender_energy_ratio_permille, DiffusionContactEvent,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! Statistical aggregation helpers for diffusion run analysis.`
	`2`	`+`
`1`	`3`	`use crate::util::stats::{average_option_u32, average_u32, mode_string as util_mode_string};`
`2`	`4`
`3`	`5`	`pub(super) use crate::util::stats::min_max_spread_u32;`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+//! Environment hooks: topology changes, degradation, partitions, and mobility events.`
	`2`	`+`
`1`	`3`	`use std::collections::BTreeMap;`
`2`	`4`
`3`	`5`	`use jacquard_core::{`