Cut shell/panel comment bloat ~47% (comments only, zero code change)

src/shell/panel/panel_audition.cpp

@@ -1,19 +1,14 @@
-// panel_audition.cpp — the audition/preview engine seam of the docked bank panel
-// (Q-W2 split of bank_panel.cpp; M5 Wave B). HOT PATH GUARDRAIL (T4-28 / Q-W2): the
-// preview path stays a DIRECT free-function call-through — no interface, no virtual
-// dispatch, no added header->TU indirection; the idle path is unchanged in shape.
+// panel_audition.cpp — the audition/preview engine seam of the docked bank panel.
+// Hot-path guardrail: the preview path stays a direct free-function call-through —
+// no interface, no virtual dispatch, no added header->TU indirection.
 //
-// Compiled into the reaper_reasampler MODULE. Includes reaper_plugin_functions.h
-// WITHOUT REAPERAPI_IMPLEMENT — main.cpp owns the API pointers; here they are
-// extern (CLAUDE.md §contract). DAW-verified, not unit tested.
+// DAW-verified, not unit tested. main.cpp owns the API pointers; here they are extern.
 
 #include <string>
 
 #include "shell/panel/panel_state.h"
 
-// Stock preview API (verified against reaper_plugin.h / reaper_plugin_functions.h):
-// PlayPreview/StopPreview drive a caller-owned preview_register_t. These are the
-// STOCK symbols (not SWS-only) — see the audition section below.
+// PlayPreview/StopPreview (stock, not SWS-only) drive a caller-owned preview_register_t.
 #define REAPERAPI_MINIMAL
 #define REAPERAPI_WANT_PlayPreview
 #define REAPERAPI_WANT_StopPreview
@@ -23,26 +18,18 @@
 
 namespace reasampler::panel {
 
-// --- Audition preview ---------------------------------------------------------
+// Audition is preview playback only — never inserts into the arrange or mutates
+// the project/bank. PlayPreview streams a caller-owned PCM_source through
+// REAPER's preview bus.
 //
-// READ-ONLY / NON-DESTRUCTIVE (load-bearing principle): audition is PREVIEW
-// playback only. It NEVER inserts into the arrange, creates items/tracks, or
-// mutates the project or bank. PlayPreview streams a caller-owned PCM_source
-// through REAPER's preview bus and touches nothing in the project.
-//
-// FLAGGED RUNTIME ASSUMPTIONS (header does not specify these; verified only by
-// signature/struct, not semantics — DAW-verify):
-//   1. REAPER's audio thread reads the preview_register_t by POINTER while the
-//      preview is active (the struct's own comment mandates a cs/mutex we init),
-//      so the register must outlive playback — we hold it in g_panel (static),
-//      never on the stack.
-//   2. StopPreview is assumed to detach the source from the audio thread BEFORE it
-//      returns, making it safe to PCM_Source_Destroy the source immediately after.
-//      This is the conventional contract (SWS' preview helpers rely on it) but is
-//      NOT documented in the header — flagged. If a rare race surfaced, the fix is
-//      a StartPreviewFade + deferred free; not done now (YAGNI, no evidence).
-//   3. m_out_chan == 0 routes to the first hardware output pair (stereo). We do not
-//      set mono (&1024). volume 1.0, loop false, curpos 0.
+// Runtime assumptions not documented in the SDK header (DAW-verify, not asserted):
+//   1. The audio thread reads preview_register_t by pointer while active, so it
+//      must outlive playback — held in g_panel (static), never on the stack.
+//   2. StopPreview is assumed to detach the source before returning, so
+//      PCM_Source_Destroy immediately after is safe (SWS' preview helpers rely on
+//      the same contract). If a race ever surfaces, the fix is a StartPreviewFade
+//      + deferred free.
+//   3. m_out_chan == 0 routes to the first hardware output pair (stereo, not mono).
 
 void initPreview() {
     if (g_panel.previewInited) return;
@@ -76,8 +63,7 @@ void deinitPreview() {
     g_panel.previewInited = false;
 }
 
-// Auditions the sample at selection ordinal `idx` of the FOCUSED region's displayed bank.
-// L7: `idx` is a DISPLAY-order (slot) ordinal, resolved through orderedIds, not a raw
+// `idx` is a display-order (slot) ordinal, resolved through orderedIds, not a raw
 // BankModel position.
 void startAudition(int idx) {
     stopAudition();