Cut shell/instrument comment bloat ~34% (comments only, zero code change)

src/shell/instrument/reaper_bridge.h

@@ -1,19 +1,11 @@
-// reaper_bridge.h — the REAPER VST-host bridge (Phase S1 read spike). THIN shell:
-// resolves REAPER API functions by name over the host context and reads the live
-// "reasampler" project ext-state. The fiddly decode lives in bridge_marshal (pure).
+// reaper_bridge.h — the REAPER VST-host bridge. Thin shell: resolves REAPER API functions
+// by name over the host context and reads the live "reasampler" project ext-state. The
+// fiddly decode lives in bridge_marshal (pure).
 //
-// VERIFIED BRIDGE MECHANISM (corrects §1a's estimate). §1a described the VST2-style
-// hostcb opcode pattern (hostcb(&effect, 0xdeadbeef, 0xdeadf00d, ...)). That is the
-// VST2 path (video_processor.h documents it for a VST2 aEffect). For a VST3 plugin the
-// bridge is exposed differently and more cleanly: REAPER passes an IHostApplication as
-// the `context` to IComponent::initialize(FUnknown* context); querying it for
-// IReaperHostApplication (vendor/reaper-sdk/sdk/reaper_vst3_interfaces.h) yields:
-//   * getReaperApi(funcname) -> resolve a REAPER API function pointer by name
-//     (the VST3 equivalent of opcode 0xdeadf00d), and
-//   * getReaperParent(3)     -> the host ReaProject* (the VST3 equivalent of the
-//     0xdeadf00e host-context fetch; 1=track, 2=take, 3=project, 4=fxdsp, 5=trackchan).
-// So a VST3 uses IReaperHostApplication, not the raw hostcb opcodes. Verified against
-// reaper_vst3_interfaces.h + reaper_plugin_functions.h at the spike.
+// Bridge mechanism: REAPER passes an IHostApplication as `context` to
+// IComponent::initialize; querying it for IReaperHostApplication yields getReaperApi
+// (resolve a REAPER API function pointer by name) and getReaperParent(3) (the host
+// ReaProject*; 1=track, 2=take, 3=project, 4=fxdsp, 5=trackchan) — not VST2 hostcb opcodes.
 
 #pragma once
 
@@ -32,48 +24,39 @@ class ReaperBridge {
 public:
     ReaperBridge() = default;
 
-    // Bind to the host. `context` is the FUnknown* REAPER hands IComponent::initialize.
-    // Returns true when the REAPER bridge is available (host is REAPER and the ext-state
-    // API resolved). Safe to call with a null or non-REAPER context — returns false.
+    // Binds to the host (`context` is the FUnknown* IComponent::initialize hands us).
+    // Returns true when the host is REAPER and the ext-state API resolved; safe to call
+    // with a null or non-REAPER context (returns false).
     bool connect(Steinberg::FUnknown* context);
 
-    // True once connect() found the REAPER host application AND resolved the ext-state
-    // functions.
     bool isConnected() const { return getProjExtState_ != nullptr; }
 
-    // Read a "reasampler" ext-state value by key from the host's active project.
-    // Returns nullopt when unconnected, when the project can't be resolved, or when the
-    // key is absent. This is the S1 read-spike entry point.
+    // Reads a "reasampler" ext-state value by key from the host's active project.
+    // Returns nullopt when unconnected, unresolvable, or the key is absent.
     //
-    // NOT REAL-TIME SAFE (it allocates a read buffer and calls into REAPER): callers on
-    // the audio thread MUST NOT invoke it. The S4 instrument reads on the main/UI thread
-    // and hands a snapshot to the process path (see reasampler_processor.cpp).
+    // NOT REAL-TIME SAFE (allocates + calls into REAPER): audio-thread callers MUST NOT
+    // invoke this. The instrument reads on the main/UI thread and hands a snapshot to
+    // the process path.
     std::optional<std::string> readReasamplerExtState(const std::string& key);
 
-    // The active project's directory (the folder holding its .rpp), forward-slashed,
-    // no trailing slash — the M4 convention persist uses to place the bank alongside
-    // the .rpp. Empty for an unsaved project or when unconnected. The instrument
-    // resolves relative sample paths against this the SAME way persist does
-    // (capture_paths::projectDirOfRpp over EnumProjects(-1)'s .rpp path). Not RT-safe.
+    // The active project's directory (forward-slashed, no trailing slash) — the same
+    // convention persist uses to place the bank alongside the .rpp. Empty for an unsaved
+    // project or when unconnected. Not RT-safe.
     std::string activeProjectDir();
 
-    // Write THIS INSTANCE's usage record (pS-usage): the ONE sanctioned instrument-side
-    // ext-state write. `usageKey` MUST carry the "rsusage_" prefix (ext_keys.h's
-    // usageKeyFor) — any other key is REFUSED here, so the read-only-BANK invariant is
-    // enforced structurally: this module can publish the instance's own usage and
-    // nothing else (banks/view/tail/assign remain unwritable from the instrument).
-    // Returns true iff written (the SetProjExtState return is checked — a dropped
-    // write must not silently claim protection). NOT RT-safe (calls into REAPER) —
-    // publish sites are the off-audio-thread reload path only. Deliberately does NOT
-    // mark the project dirty: a usage change always rides a component-state change
-    // that already does.
+    // Writes THIS INSTANCE's usage record: the ONE sanctioned instrument-side ext-state
+    // write. `usageKey` MUST carry the "rsusage_" prefix (ext_keys.h's usageKeyFor); any
+    // other key is refused, enforcing the read-only-bank invariant structurally (banks/
+    // view/tail/assign stay unwritable from the instrument). Returns true iff written
+    // (the SetProjExtState return is checked). NOT RT-safe — publish sites are the
+    // off-audio-thread reload path only. Deliberately does NOT mark the project dirty: a
+    // usage change always rides a component-state change that already does.
     bool writeUsageExtState(const std::string& usageKey, const std::string& value);
 
-    // The canonical "{XXXXXXXX-...}" GUID string of the track hosting this FX instance
-    // (getReaperParent(1) -> GetTrackGUID -> guidToString — the same rendering as the
-    // extension's track_guid::guidString, so usage records and the extension's live-FX
-    // enumeration compare byte-equal). Empty when unconnected or no track context (the
-    // usage reader then falls back to any-instance liveness — fail-safe). Not RT-safe.
+    // The canonical GUID string of the track hosting this FX instance (same rendering as
+    // the extension's track_guid::guidString, so usage records compare byte-equal
+    // against its live-FX enumeration). Empty when unconnected or no track context (the
+    // usage reader then falls back to any-instance liveness). Not RT-safe.
     std::string currentTrackGuid();
 
 private:
@@ -84,18 +67,14 @@ private:
     using EnumProjExtStateFn = bool (*)(void* proj, const char* extname, int idx,
                                         char* keyOut, int keyOut_sz, char* valOut,
                                         int valOut_sz);
-    // EnumProjects(-1, projfnOut, sz) -> active project + its .rpp path (SDK line
-    // ~1264). The instrument uses idx=-1 (current tab) so it follows the active project,
-    // and reads the .rpp path from the out-buffer exactly as the persist shell
-    // (ext_state_io.cpp) does.
+    // EnumProjects(-1, projfnOut, sz) -> active project + its .rpp path. idx=-1 (current
+    // tab) follows the active project, same convention as the persist shell.
     using EnumProjectsFn = void* (*)(int idx, char* projfnOut, int projfnOut_sz);
-    // SetProjExtState(proj, extname, key, value) -> int (SDK line ~6290). Used ONLY by
-    // writeUsageExtState (prefix-guarded) — see the read-only-bank note there.
+    // Used ONLY by writeUsageExtState (prefix-guarded) — see the read-only-bank note there.
     using SetProjExtStateFn = int (*)(void* proj, const char* extname, const char* key,
                                       const char* value);
-    // GetTrackGUID(MediaTrack*) -> GUID* (SDK ~3562) + guidToString(const GUID*, char*
-    // destNeed64) (SDK ~3848). Both held as opaque-pointer signatures so the header
-    // stays SDK-type-free; the GUID* is passed straight through, never dereferenced here.
+    // Opaque-pointer signatures so the header stays SDK-type-free; the GUID* is passed
+    // straight through, never dereferenced here.
     using GetTrackGuidFn = void* (*)(void* tr);
     using GuidToStringFn = void (*)(const void* g, char* destNeed64);