refactor: update various comments

Signed-off-by: Maika Namuo <httpworldview@gmail.com>

Author: httpsworldview

CONTRIBUTING.md

@@ -28,9 +28,9 @@ the existing visuals, but in short:
 4. The oscilloscope uses normalized autocorrelation period estimation
    and waveform-template correlation to keep traces stable across
    complex periodic signals and visible channel selections.
-5. The stereometer separates bands using LR4 Butterworth filters,
-   along with linear and log scaling. The correlation meter uses those
-   same Butterworth crossings.
+5. The stereometer uses LR4 (cascaded Butterworth) crossovers and
+   linear or power-law radial scaling. Multiband correlation uses
+   the same crossover outputs.
 6. The loudness meter implements K-weighting relative to full
    scale/LUFS momentary/short-term, True Peak, and RMS
    fast/slow. Standards used include ITU-R BS.1770.

src/domain.rs

@@ -5,7 +5,7 @@ pub mod routing {
     use serde::{Deserialize, Serialize};
     use std::{collections::HashSet, sync::Arc};
 
-    /// Stable key for one application's capture policy.
+    /// Shared stream key for persisted capture policy.
     #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
     #[serde(transparent)]
     pub struct StreamIdentity(pub(crate) Arc<str>);

src/infra/pipewire.rs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Maika Namuo
 
-//! Owned PipeWire graph tap and its two narrow cross-thread interfaces.
+//! Threaded PipeWire capture with ordered audio delivery.
 
 mod graph;
 mod policy;

src/infra/pipewire/stream.rs

@@ -18,6 +18,7 @@ use std::rc::Rc;
 use tracing::{error, info};
 
 const DESCRIPTION: &str = "OpenMeters Audio Tap";
+// Requested latency at DEFAULT_SAMPLE_RATE.
 const LATENCY_FRAMES: u32 = 256;
 const EMPTY: i32 = spa::sys::SPA_CHUNK_FLAG_EMPTY as i32;
 const NATIVE_F32: spa::param::audio::AudioFormat =

src/infra/pipewire/transport.rs

@@ -13,12 +13,17 @@ use std::sync::{Arc, RwLock};
 use std::time::{Duration, Instant};
 use tracing::info;
 
+// Packet frame cap, independent of PipeWire's quantum.
 const BLOCK_FRAMES: usize = 256;
 const BLOCK_SAMPLES: usize = BLOCK_FRAMES * MAX_CAPTURE_CHANNELS;
+// Front-packet age from its end; current activity epoch only.
 const MAX_BACKLOG: Duration = Duration::from_secs(1);
+// 4/3 s of full packets at maximum rate.
 const RING_BLOCKS: usize = (MAX_CAPTURE_SAMPLE_RATE as usize * 4).div_ceil(BLOCK_FRAMES * 3);
 const PCM_FLUSH_SAMPLES: usize = BLOCK_SAMPLES * 4;
+// Packet-duration target, not a flush timer.
 const PACKET_FLUSH_INTERVAL: Duration = Duration::from_millis(50);
+// Minimum grace for packet continuity and inferred streaming silence.
 const IDLE_WATCHDOG: Duration = Duration::from_millis(100);
 
 fn packet_frame_limit(rate: u64) -> usize {

src/meter.rs

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Maika Namuo
 
-//! Presentation-side ownership of the ordered audio timeline.
+//! Feeds audio and silence to visuals in timeline order.
 //!
 //! Capture stays at its negotiated PipeWire quantum. DSP work is amortized into
 //! sample-rate-scaled batches so compositor cadence does not become DSP cadence.
@@ -15,7 +15,7 @@ use std::time::Instant;
 const SILENCE_CHUNK_FRAMES: usize = 4_096;
 const DSP_BATCH_FRAMES_AT_48K: usize = 256;
 const MAX_DSP_INGEST_FRAMES_AT_48K: usize = 1_024;
-// Cover the three-second loudness window plus recursive filter settling.
+// Per-span limit; longer silence resets audio state.
 const MAX_SILENCE_SECONDS: u64 = 4;
 
 fn scaled_samples(frames_at_48k: usize, format: AudioFormat) -> usize {

src/ui/app.rs

@@ -36,6 +36,7 @@ use windowing::{
 };
 
 const TOAST_DISPLAY_DURATION: Duration = Duration::from_secs(2);
+// Event-driven retry cooldown, not a timer.
 const BAR_RETRY_WINDOW: Duration = Duration::from_secs(5);
 const MAINTENANCE_INTERVAL: Duration = Duration::from_millis(100);
 const BAR_RESIZE_HANDLE_THICKNESS: f32 = 6.0;

src/ui/settings.rs

@@ -168,7 +168,7 @@ fn get_closest_hop_divisor(fft_size: usize, hop_size: usize) -> usize {
         .unwrap()
 }
 
-// Preserve the hop:fft ratio when fft_size changes.
+// Preserve the nearest supported hop divisor.
 fn update_fft_size(fft_size: &mut usize, hop_size: &mut usize, new_size: usize) -> bool {
     let hop_divisor = get_closest_hop_divisor(*fft_size, *hop_size);
     if !set(fft_size, new_size) {

src/ui/widgets/frame_clock.rs

@@ -16,6 +16,7 @@ use std::sync::{
 };
 use std::time::{Duration, Instant};
 
+// Redraw polling interval and popout takeover delay.
 const WATCHDOG_INTERVAL: Duration = Duration::from_millis(50);
 
 fn next_deadline(deadline: Instant, now: Instant, interval: Duration) -> Instant {
@@ -35,6 +36,7 @@ fn display_frame_due(
         })
 }
 
+// Low bit: suspended. Upper bits: redraw/reset counter.
 #[derive(Clone, Default)]
 pub(in crate::ui) struct FrameHeartbeat(Arc<AtomicU64>);
 

src/util/audio.rs

@@ -19,6 +19,7 @@ pub(crate) use self::{
 
 pub const DEFAULT_SAMPLE_RATE: f32 = 48_000.0;
 pub const MAX_SAMPLE_RATE: f32 = 768_000.0;
+// Caps configured FFT lengths and retained oscilloscope/stereometer frames.
 pub const MAX_DSP_BUFFER_LEN: usize = 1 << 20;
 pub const BAND_SPLITS_HZ: [f32; 2] = [200.0, 2000.0];
 pub const BAND_COUNT: usize = BAND_SPLITS_HZ.len() + 1;