style: use Rust doc comments (///) instead of C-style /** */; clarify mount API header

src/orchestrator/run.rs

@@ -81,13 +81,25 @@ impl Context {
         }
     }
 
-    /// Builder: enable showing summary to stdout.
+    /// Enable or disable preview JSON emission to stdout.
+    ///
+    /// When set to true (e.g. via `--show`), orchestrator:
+    /// - Prints a compact JSON summary to stdout
+    /// - Skips empty-disk enforcement to allow non-destructive planning
+    ///
+    /// Returns the updated Context for builder-style chaining.
     pub fn with_show(mut self, show: bool) -> Self {
         self.show = show;
         self
     }
 
-    /// Builder: override report path.
+    /// Override the report output path used by preview mode.
+    ///
+    /// When provided (e.g. via `--report /path/file.json`), orchestrator:
+    /// - Writes the same JSON summary to the given path
+    /// - Continues to respect `--show` (stdout) when also set
+    ///
+    /// Returns the updated Context for builder-style chaining.
     pub fn with_report_path(mut self, path: Option<String>) -> Self {
         self.report_path_override = path;
         self
@@ -185,6 +197,13 @@ pub fn run(ctx: &Context) -> Result<()> {
     Ok(())
 }
 
+/// Build a DeviceFilter from the runtime configuration.
+///
+/// Compiles include/exclude regex patterns and carries the minimum-size threshold
+/// as well as the removable-device policy (allow_removable).
+///
+/// Errors:
+/// - Returns Error::Validation when a regex pattern is invalid.
 fn build_device_filter(cfg: &Config) -> Result<DeviceFilter> {
     let mut include = Vec::new();
     let mut exclude = Vec::new();
@@ -210,6 +229,14 @@ fn build_device_filter(cfg: &Config) -> Result<DeviceFilter> {
     })
 }
 
+/// Enforce empty-disk policy for all discovered target disks.
+///
+/// For each disk:
+/// - Uses idempotency::is_empty_disk() to verify no partitions or FS signatures exist
+/// - Returns Error::Validation on the first non-empty disk encountered
+///
+/// This function MUST NOT be called when running in preview mode, as orchestrator
+/// skips emptiness enforcement to allow planning on live systems.
 fn enforce_empty_disks(disks: &[Disk]) -> Result<()> {
     for d in disks {
         let empty = idempotency::is_empty_disk(d)?;
@@ -223,6 +250,7 @@ fn enforce_empty_disks(disks: &[Disk]) -> Result<()> {
     Ok(())
 }
 
+#[inline]
 fn role_str(role: partition::PartRole) -> &'static str {
     match role {
         partition::PartRole::BiosBoot => "bios_boot",
@@ -232,6 +260,17 @@ fn role_str(role: partition::PartRole) -> &'static str {
     }
 }
 
+/// Build the preview JSON payload for `--show` / `--report`.
+///
+/// Includes:
+/// - version, timestamp, status="planned"
+/// - topology string, alignment and empty-disk policy flag
+/// - discovered disks (path, size_bytes, rotational, model, serial)
+/// - partition_plan per disk (role, size_mib or null for remainder, gpt_name)
+/// - filesystems_planned: inferred FS kinds per topology and labels
+/// - mount: scheme summary and target template (e.g., "/var/cache/{UUID}")
+///
+/// This function is non-destructive and performs no probing beyond the provided inputs.
 fn build_summary_json(disks: &[Disk], plan: &partition::PartitionPlan, cfg: &Config) -> Result<serde_json::Value> {
     // Disks summary
     let disks_json: Vec<serde_json::Value> = disks