Cut shell/capture comment bloat ~33% (comments only, zero code change)

src/shell/capture/provenance_shell.h

@@ -1,19 +1,16 @@
 #pragma once
-// provenance_shell — the REAPER-facing reads Milestone 10 needs, in one place.
-//
-// The PURE provenance module (provenance.h) owns the fingerprint encoding, the
-// recipe model, the FX-identity fold, and the parent-detection DECISION — all over
-// plain strings/values. This shell gathers those strings/values FROM REAPER:
+// The REAPER-facing reads provenance needs, in one place. The pure provenance
+// module (provenance.h) owns the fingerprint encoding, the recipe model, the
+// FX-identity fold, and the parent-detection decision, all over plain
+// strings/values; this shell gathers those strings/values from REAPER:
 //   * the in-scope FX-chain identity of a source track (name/GUID/enabled rows),
 //   * the media-file paths of a resolved capture's source items,
 //   * the active book's bank samples resolved to absolute file paths,
 //   * a canonical track-GUID string back to a live MediaTrack*.
 //
-// REAPER-facing: the .cpp includes reaper_plugin_functions.h WITHOUT
-// REAPERAPI_IMPLEMENT (main.cpp owns the API pointers; here they are extern —
-// CLAUDE.md §contract). MediaTrack is forward-declared so this header stays
-// SDK-lite. It depends on the pure provenance module (FxIdentityEntry / recipe /
-// BankFileRef) and bank_book (to enumerate the active book's samples).
+// The .cpp includes reaper_plugin_functions.h WITHOUT REAPERAPI_IMPLEMENT
+// (main.cpp owns the API pointers). MediaTrack is forward-declared so this header
+// stays SDK-lite.
 
 #include <optional>
 #include <string>
@@ -28,53 +25,43 @@ namespace reasampler {
 
 class BankBook;
 
-// Real-namespace-home using-declaration (Q-W6: the namespaces.h shim is retired).
 using model::BankFileRef;
 
 // The in-scope FX-chain identity of a source track (Track scope), folded to the
-// pure provenance string. Reads the track's own FX chain via TrackFX_GetCount /
-// TrackFX_GetFXName / TrackFX_GetFXGUID / TrackFX_GetEnabled in chain order.
+// pure provenance string via the track's own FX chain (TrackFX_*) in chain order.
 std::string fxChainIdentityForTrack(MediaTrack* tr);
 
 // The in-scope FX-chain identity for Item scope: enumerates each item's active
-// take FX chain via TakeFX_GetCount / TakeFX_GetFXName / TakeFX_GetFXGUID /
-// TakeFX_GetEnabled, in item order then FX order, combined with
-// combineChainIdentities so distinct per-item partitions never collide. Returns
-// the combined identity string (empty combined identity for a no-FX or no-item
-// set). The items vector is the same source-item set the shell collected for the
-// item-scope capture (selected items whose owning tracks were also collected).
+// take FX chain (TakeFX_*), in item order then FX order, combined with
+// combineChainIdentities so distinct per-item partitions never collide. `items` is
+// the same source-item set the shell collected for the item-scope capture.
 std::string fxChainIdentityForItems(const std::vector<MediaItem*>& items);
 
-// Reads the media-file path of every SELECTED media item's active take source
-// (GetMediaItemTake_Source -> GetMediaSourceFileName), normalized to forward-slash.
-// Unresolvable items (no take / no source / empty name) are omitted — never an
-// empty string in the result, so detectParent's "not in bank" branch is honest.
-// The active-project selection is read directly (mirrors main.cpp's collectors).
-// This is the ITEM-scope source set (the user selected the items being resampled).
+// The media-file path of every selected media item's active take source,
+// normalized to forward-slash. Unresolvable items (no take/source/name) are
+// omitted — never an empty string in the result, so detectParent's "not in bank"
+// branch is honest. This is the item-scope source set.
 std::vector<std::string> selectedItemSourceFiles();
 
-// The TRACK-scope source set: the media-file paths of the items ON `tracks` that
-// OVERLAP the capture range [startSeconds, endSeconds). For a track capture the user
-// selects the track, not the item, so the "what audio is being captured" set is the
-// range-overlapping items on the source tracks. Same normalize + omit-unresolvable
-// contract as selectedItemSourceFiles. An item overlaps iff its [pos, pos+len)
-// intersects the range with positive overlap (a zero-length touch does not count).
+// The track-scope source set: media-file paths of the items on `tracks` that
+// overlap the capture range [startSeconds, endSeconds). A track capture selects
+// the track, not the item, so this is what "the source audio" means for it. Same
+// normalize + omit-unresolvable contract as selectedItemSourceFiles; an item
+// overlaps iff its [pos, pos+len) intersects the range with positive overlap (a
+// zero-length touch does not count).
 std::vector<std::string> trackItemSourceFiles(const std::vector<MediaTrack*>& tracks,
                                               double startSeconds, double endSeconds);
 
-// Enumerates the ACTIVE book's samples across every bank (pool + named) as pure
-// BankFileRefs — each sample id paired with its file resolved to a normalized
-// ABSOLUTE path against `projectDir` (resolveBankFile + normalizeSlashes). A sample
-// whose path cannot be resolved (empty projectDir / empty relativePath) is emitted
-// with an empty absolutePath, which detectParent never matches. `projectDir` is the
-// current .rpp parent (the shell resolves it; empty -> all refs unresolved).
+// Enumerates the active book's samples across every bank as pure BankFileRefs,
+// each id paired with its file resolved to an absolute path against `projectDir`.
+// An unresolvable path (empty projectDir/relativePath) gets an empty absolutePath,
+// which detectParent never matches.
 std::vector<BankFileRef> bankFileRefs(const BankBook& book, const std::string& projectDir);
 
-// Resolves a canonical track-GUID string (guidString form) to a live MediaTrack*
-// in the active project by scanning tracks and comparing guidString(tr). Returns
-// nullptr when no live track carries that GUID (the source track was deleted since
-// capture — a re-capture failure mode the caller reports). The master track is not
-// scanned (it has no membership GUID and is never a capture source).
+// Resolves a canonical track-GUID string to a live MediaTrack* in the active
+// project. Returns nullptr when no live track carries that GUID (the source track
+// was deleted since capture — a re-capture failure mode the caller reports). The
+// master track is not scanned (no membership GUID, never a capture source).
 MediaTrack* trackByGuid(const std::string& guid);
 
 }  // namespace reasampler