docs(audio): improve doc comments on key modules (TODO-031)

Add/improve dart doc comments for frame converters, AudioEngineConfig,
VadOutput variants, WebRtcFallbackVad, SileroOnnxVad, AppleCoreMlVad.

crates/chanora_audio/src/engine/mod.rs

@@ -361,7 +361,7 @@ pub fn list_audio_devices() -> AudioDeviceList {
     }
 }
 
-/// Engine configuration.
+/// Engine configuration for the audio subsystem.
 #[derive(Clone)]
 pub struct AudioEngineConfig {
     /// Input gain applied before encoding (1.0 = pass-through).

crates/chanora_audio/src/frame.rs

@@ -16,12 +16,12 @@ pub const FRAME_10MS_SAMPLES: usize = 480;
 /// Samples in one 20 ms mono frame at 48 kHz.
 pub const FRAME_20MS_SAMPLES: usize = 960;
 
-/// Convert i16 PCM to normalized f32 PCM.
+/// Convert i16 PCM sample to normalized f32 PCM (-1.0 to 1.0).
 pub fn i16_to_f32(sample: i16) -> f32 {
     sample as f32 / i16::MAX as f32
 }
 
-/// Convert normalized f32 PCM to saturated i16 PCM.
+/// Convert normalized f32 PCM to saturated i16 PCM (clamps to [-1.0, 1.0]).
 pub fn f32_to_i16(sample: f32) -> i16 {
     (sample.clamp(-1.0, 1.0) * i16::MAX as f32) as i16
 }

crates/chanora_audio/src/vad/apple_coreml.rs

@@ -89,7 +89,8 @@ unsafe fn resolve_symbol(name: &'static [u8]) -> Option<*mut c_void> {
     }
 }
 
-/// 16 kHz detector backed by Swift `SileroCoreML.SileroVAD`.
+/// 16 kHz detector backed by Swift Silero CoreML VAD.
+/// Processes 16 kHz frames and outputs speech probability.
 pub struct AppleCoreMlVad {
     handle: *mut c_void,
     symbols: AppleSileroSymbols,

crates/chanora_audio/src/vad/mod.rs

@@ -22,6 +22,7 @@ use resampler::{Downsampler48to16, INPUT_FRAME_10MS};
 pub use silero_onnx::SileroOnnxVad;
 
 /// Voice activity detector output for one 10 ms frame.
+/// Contains speech probability and binary decision.
 #[derive(Debug, Clone, Copy)]
 pub struct VadOutput {
     /// Speech confidence in the inclusive range `[0.0, 1.0]`.
@@ -36,7 +37,8 @@ pub trait VoiceActivityDetector: Send {
     fn process_10ms(&mut self, samples: &[f32]) -> VadOutput;
 }
 
-/// Realtime-safe WebRTC VAD used when a model runtime is unavailable.
+/// Realtime-safe WebRTC VAD fallback when ONNX runtime is unavailable.
+/// Uses aggressive mode at 48 kHz for voice detection.
 pub struct WebRtcFallbackVad {
     vad: webrtc_vad::Vad,
     frame_i16: [i16; INPUT_FRAME_10MS],
@@ -75,8 +77,8 @@ impl VoiceActivityDetector for WebRtcFallbackVad {
     }
 }
 
-/// Wraps any `VoiceActivityDetector` that operates at 16 kHz and
-/// downsamples 48 kHz input before forwarding.
+/// Wraps any `VoiceActivityDetector` operating at 16 kHz,
+/// downsampling 48 kHz input before forwarding to the detector.
 pub struct Resampled16kHzVad<D: VoiceActivityDetector> {
     inner: D,
     downsampler: Downsampler48to16,