Cut shell/actions, bank_ops, app comment bloat ~48% (comments only, zero code change)

src/shell/bank_ops/bank_ops.h

@@ -1,22 +1,14 @@
 #pragma once
-// bank_ops — the promptless bank-verb seam (Q-W6 lift of the Q-W4 single-owner
-// verbs out of shell/panel/panel_bank_ops into a NON-UI home). Each verb is a model
-// op on the given session's BankBook + persistBankOp (undo-batched ext-state
-// persist) — NO prompts, NO message boxes, NO panel-state nudges, NO panel-global
-// reads. The two UX surfaces consume these as thin skins:
+// bank_ops — the promptless bank-verb seam. Each verb is a model op on the given
+// session's BankBook + persistBankOp (undo-batched ext-state persist) — NO prompts,
+// NO message boxes, NO panel-state nudges. Two UX surfaces consume these as thin
+// skins: shell/panel/panel_bank_ops (menu prompts/confirms/repaints) and
+// shell/actions/bank_actions (bindable family, text prompts/console feedback).
 //
-//   * shell/panel/panel_bank_ops — the panel's menu handlers (prompts / confirms /
-//     repaints), passing the panel's live session.
-//   * shell/actions/bank_actions — the bindable family (text prompts / console
-//     feedback), passing its registered session.
-//
-// The session arrives BY REFERENCE: there is exactly one session pointer question
-// per call site (the caller's), so a missing session can never be half-reported as
-// a model rejection from in here (the Q-W4 review's fail-safe-collapse concern).
-// Every verb returns whether the model accepted the mutation — a rejected op
-// persists nothing and opens no undo point.
-//
-// REAPER-facing (persist + undo blocks + GUID minting) but SDK-free in this header.
+// The session arrives BY REFERENCE, so a missing session can never be
+// half-reported as a model rejection from in here. Every verb returns whether the
+// model accepted the mutation — a rejected op persists nothing and opens no undo
+// point. REAPER-facing (persist + undo blocks + GUID minting) but SDK-free header.
 
 #include <string>
 #include <vector>
@@ -25,58 +17,47 @@ namespace reasampler {
 
 class ReaSamplerSession;
 
-// Mints a stable GUID bank id, creates `name` in the book. Returns the new bank id,
-// or "" when the model rejects the name (duplicate, trimmed + case-insensitive).
-// Create is purely organizational — no generation bump.
+// Returns "" when the model rejects the name (duplicate, trimmed + case-insensitive).
+// Purely organizational — no generation bump.
 std::string bankOpCreate(ReaSamplerSession& session, const std::string& name);
 
-// Renames `bankId`. False when the model rejects (pool un-renamable / name in use).
+// False when the model rejects (pool un-renamable / name in use).
 bool bankOpRename(ReaSamplerSession& session, const std::string& bankId,
                   const std::string& newName);
 
-// Deletes `bankId`. False when the model rejects (pool un-deletable). The caller
-// passes `bumpGeneration` from the member count it read BEFORE any evacuate/delete
-// (an evacuate-then-delete flow must still bump on the ORIGINAL membership).
+// False when the model rejects (pool un-deletable). `bumpGeneration` should be the
+// member count read BEFORE any evacuate/delete (an evacuate-then-delete flow must
+// still bump on the ORIGINAL membership).
 bool bankOpDelete(ReaSamplerSession& session, const std::string& bankId,
                   bool bumpGeneration);
 
-// Evacuates `bankId`'s members to the pool. False when the model rejects (the pool
-// itself). Bumps the generation (membership changed).
+// False when the model rejects (the pool itself). Bumps the generation.
 bool bankOpEvacuate(ReaSamplerSession& session, const std::string& bankId);
 
-// Activates `bankId` as the capture target. False on an unknown id. No bump.
+// False on an unknown id. No bump.
 bool bankOpActivate(ReaSamplerSession& session, const std::string& bankId);
 
-// Moves (copy=false) or copies (copy=true) `sampleIds` from `srcBankId` to
-// `destBankId` (index-only; files never relocate). Returns whether the index
-// actually mutated — the verb-aware no-op guardrail: a COPY collapse changes
-// nothing (no undo point); a MOVE collapse did remove the source entry (counts).
-// Persists ONE undo point ("move/copy sample(s)") only when mutated.
+// Index-only; files never relocate. Returns whether the index actually mutated — a
+// COPY collapse changes nothing (no undo point), a MOVE collapse did remove the
+// source entry (counts). Persists one undo point only when mutated.
 bool bankOpTransfer(ReaSamplerSession& session,
                     const std::vector<std::string>& sampleIds,
                     const std::string& srcBankId, const std::string& destBankId,
                     bool copy);
 
-// Removes `sampleIds` from `srcBankId` (index-only, this-bank scope; never deletes
-// bytes). Returns whether anything was removed; persists one undo point when so.
+// Index-only, this-bank scope; never deletes bytes. Persists one undo point when
+// anything was removed.
 bool bankOpRemove(ReaSamplerSession& session,
                   const std::vector<std::string>& sampleIds,
                   const std::string& srcBankId);
 
-// Persists a completed bank-index verb as a single REAPER undo point (R-B).
-// Wraps the session persist (SetProjExtState) in a Begin/End block with
-// UNDO_STATE_MISCCFG so the bank op is one Ctrl-Z. On an unsaved / no-active project
-// the persist no-ops and the block is closed with an empty label + zero flag (REAPER
-// discards it). Callers must invoke this ONLY after a successful/effective mutation —
-// rejected ops (duplicate name, un-deletable pool, etc.) must return before reaching
-// here so no empty undo point is ever opened for a no-op.
+// Wraps the session persist in a Begin/End undo block (UNDO_STATE_MISCCFG) so the
+// bank op is one Ctrl-Z; on an unsaved/no-active project the block closes empty
+// (REAPER discards it). Call ONLY after an effective mutation.
 //
-// S9 bank-generation bump: pass `bumpGeneration = true` for a verb that changes what a
-// live instance would PLAY — move / copy / remove / evacuate / delete-with-members. Leave
-// it false (the default) for a PURELY ORGANIZATIONAL verb — create / rename / activate /
-// reorder. The bump (when requested) happens INSIDE the block, BEFORE the persist, so
-// the stamped counter rides the same ext-state write and undo captures the pre/post
-// generation with the rest of the blob.
+// `bumpGeneration = true` for a verb that changes what a live instance would PLAY;
+// leave false for a purely organizational verb. The bump happens INSIDE the block,
+// before the persist, so the stamped counter rides the same ext-state write.
 void persistBankOp(ReaSamplerSession& session, const char* label,
                    bool bumpGeneration = false);