Add header comments to the source files

Every source file in ui, app, game, formats, cli, audio and launch that had none
now starts with a short English comment: what it implements, what state it owns
and how it relates to its neighbours (request/acknowledge flow, pairs of files,
random generator use). Comment lines only; the full build and the runnable
tests are unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
ClaudeandClaude Sonnet 5.5 committed 2026-11-06 09:15:23 +01:00
1 parent aa6ec96305
commit 287b5a9251
324 files changed
+1186

No files matched your search

+6
View File
@@ -1,4 +1,10 @@
// SPDX-License-Identifier: GPL-3.0-only
// All-or-nothing wrapper for one UI window action on a CareerSession (used by
// desktop_actions.cpp and window_actions.cpp). It snapshots the game state, the RNG and the
// revision counter, runs the action and, if the action returns false or throws, restores
// all three, so a rejected action leaves no half-applied change behind.
// apply_native() is the variant for owners that keep their state in CareerSession::state().
// Header-only; owns no state of its own.
#pragma once
#include "app/career_session.hpp"
+7
View File
@@ -1,4 +1,11 @@
// SPDX-License-Identifier: GPL-3.0-only
// Glue between the original-audio engine (src/audio/playback.hpp) and the app: builds the
// asset set from the game's sound containers and the frequency/operator tables read from the
// executable, derives the music/click/match-sound options from the saved settings bytes of
// the GameState, and sends sound commands only when the original sound path is ready.
// OriginalMouseSound is an SDL event watch that plays the click sound on each real mouse
// button press; it touches only the Playback object, never the GameState, because the
// watch can run on SDL's event thread. Header-only.
#include "formats/executable_layout.hpp"
#pragma once
+12
View File
@@ -1,4 +1,16 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of CareerSession (career_session.hpp): the engine side of the career. It
// owns the GameState, the two random generators, the turn driver and every "owner" of an
// open modal window (transfer editor, league table, bank, contracts, ...), and it is the
// only code the UI flow reaches into for game logic, through the controller.
// Request/acknowledge model: the UI sends a typed request that carries the revision it
// observed; the session checks that revision, applies the change (or rejects it with an
// error text), bumps the revision only when something changed and returns a projection or
// dispatch result. The front end then acknowledges that result (controller.cpp and the
// *Actions facades roll the session back if the acknowledgement fails). Live match events and
// notices flow the other way: the session calls presenter hooks synchronously and waits.
// This file also contains the checkpoint/restore code used by those rollbacks, the career
// start (options, manager join), save/load through the .FBM container and autosave.
#include "formats/native_save_version.hpp"
#include "formats/badge_policy.hpp"
#include "game/calendar.hpp"
+14
View File
@@ -1,4 +1,18 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the controller (controller.hpp): the request/acknowledge model between
// the UI flow, the controller and the session.
// 1. The SDL loop in main.cpp feeds input to ui::StartupFlow, which returns a FlowResult
// with a FlowRequest (desk action, transfer, friendly match, load game, ...).
// 2. serve_flow_request() is the single entry for that request. It rejects requests whose
// revision no longer matches (stale UI), or that are blocked by an open owner.
// 3. It forwards the request to the matching *Actions facade (desktop_actions.*,
// window_actions.*), which runs it on the CareerSession inside a rollback transaction.
// 4. The result is acknowledged back to the flow (for example flow.acknowledge_*,
// show_*), which then changes what is drawn; rendering alone never advances the engine.
// 5. A non-empty return string is an error message (main.cpp prints it); "career_complete"
// ends the program. The shared revision counter grows only when state really changed.
// Presenters (dialogs, live match frames) are optional hooks; an empty hook means the
// headless default. The anonymous namespace holds friendly-match and national-friendly helpers.
#include "formats/badge_policy.hpp"
#include "formats/executable_layout.hpp"
#include "app/controller.hpp"
+7
View File
@@ -1,4 +1,11 @@
// SPDX-License-Identifier: GPL-3.0-only
// The controller: the one synchronous boundary between the UI flow (ui::StartupFlow) and
// the engine session (CareerSession). The flow turns a click or key into a ui::FlowResult
// that carries a request; serve_flow_request() validates it against the current revision,
// calls the session, and acknowledges the outcome back to the flow. Everything the engine
// needs from the front end (dialogs, live match presentation, notices) is passed in as
// std::function "presenter" hooks, so tests can drive the same code without a window.
// Pairs with controller.cpp; the real hooks are supplied by main.cpp.
#pragma once
#include "app/career_session.hpp"
+4
View File
@@ -1,4 +1,8 @@
// SPDX-License-Identifier: GPL-3.0-only
// Debug mode (command line -debug): a process-wide, mutex-protected log file plus numbered
// automatic savegames, both kept in one folder. State is a function-local static; every
// function is a no-op until init() has succeeded, so callers may log unconditionally.
// init() also redirects stderr into the same folder. Header-only.
#pragma once
#include <chrono>
+6
View File
@@ -1,4 +1,10 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the desk-level action facades declared in desktop_actions.hpp. Each
// method checkpoints the relevant session owner, runs the request through CareerSession,
// lets the accept callback acknowledge the result to the UI, and rolls everything back via
// detail::apply_window if the callback returns false or throws. Errors are returned through
// the std::string& error parameter. The request/acknowledge flow as a whole is described
// at the top of controller.cpp.
#include "formats/executable_layout.hpp"
#include "app/desktop_actions.hpp"
#include "app/action_transaction.hpp"
+7
View File
@@ -1,4 +1,11 @@
// SPDX-License-Identifier: GPL-3.0-only
// Application-boundary facades for desk-level windows: one small class per owner (desk
// settings, balance plan, other games, top scorers, opportunities, manager join, mailbox,
// menu layout, environment, reschedule, contracts, friendly matches). Each wraps a
// CareerSession reference; its apply() runs an action under a rollback transaction (see
// action_transaction.hpp), and open()/dispatch() take the UI request plus the shared
// revision counter and an optional "accept" callback that carries the front end's
// acknowledgement. Implemented in desktop_actions.cpp; window_actions.hpp holds the club windows.
#pragma once
#include "app/career_session.hpp"
+6
View File
@@ -1,4 +1,10 @@
// SPDX-License-Identifier: GPL-3.0-only
// SDL event helpers for the live match-day presentation, which runs while the engine is
// synchronously paused in its observer hook. live_matchday_board_side() turns a mouse press
// into a side (0 or 1) of the board only at the allowed minutes and screen intervals;
// pump_live_matchday_events() drains the SDL queue, reports a quit request and an ESC skip
// through its return value / out-parameter, and re-queues only non-interactive system events.
// Header-only; owns no state.
#pragma once
#include <SDL.h>
+15
View File
@@ -1,4 +1,19 @@
// SPDX-License-Identifier: GPL-3.0-only
// Entry point of the SDL front end (openbmh_play) and the owner of everything the player
// sees and hears: window, renderer, 320x240 indexed canvas, audio Playback, quit handling.
// It parses the command line, resolves the game data (src/launch), builds ui::StartupFlow and
// then runs the event loops. The request/acknowledge model works like this:
// - Input events go to the StartupFlow; a click or key may return a FlowResult carrying a
// FlowRequest (kickoff, desk action, transfer, save/load, ...).
// - main.cpp's handle() passes that result to app::serve_flow_request() (controller.cpp),
// together with the shared revision counter and a large set of presenter lambdas.
// - The controller asks the CareerSession (career_session.cpp, the engine side) to do the
// work and acknowledges the outcome to the flow; the engine may call a presenter lambda
// back, synchronously, to show a modal dialog or a live match frame, which runs its own
// nested event loop here until the player answers.
// - A non-empty message from the controller is printed to stderr; "career_complete" ends
// the program; the screen is redrawn only when the flow marks it dirty.
// The engine never draws and the UI never advances the engine on its own.
#include "formats/badge_policy.hpp"
#include "formats/executable_layout.hpp"
#include "app/start_screen.hpp"
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Mouse pointer for the pitch page. SDL owns the pointer position; the UI only hands over
// the original 11x11 pixel bitmap (121 ARGB values). PitchPointer builds an SDL colour
// cursor from it, enlarged by an integer scale derived from the window size in points, and
// caches it until the pixels or the scale change. set_default() sets the bitmap used on all
// other pages. Header-only; the cursor is freed in clear() / the destructor.
#pragma once
#include <SDL.h>
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Quit confirmation (a deliberate deviation from the original): a native message box in
// German or English whose default button is "Cancel". poll() and peep() wrap
// SDL_PollEvent / SDL_PeepEvents and drop SDL_QUIT events the user does not confirm. The
// dialog is shown from the UI thread only, and a dialog that fails to open counts as "not
// confirmed". The presenter is injectable (defaults to SDL_ShowMessageBox). Header-only.
#pragma once
#include <SDL.h>
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of StartScreen (start_screen.hpp): decodes the embedded JPEG
// (start_screen_data.hpp) with stb_image into an RGB24 texture, switches the renderer's
// logical size to the image size while presenting and restores the previous logical size in
// the destructor. Errors are reported as std::runtime_error; the stb_image implementation
// is compiled into this file only (JPEG decoding, no stdio).
#include "app/start_screen.hpp"
#include "app/start_screen_data.hpp"
#include <SDL.h>
+4
View File
@@ -1,4 +1,8 @@
// SPDX-License-Identifier: GPL-3.0-only
// Start screen shown before the game data is loaded: one embedded picture drawn with its
// own renderer logical size, independent of the indexed game canvas. Owns the SDL
// texture; non-copyable. Implemented in start_screen.cpp, the image bytes come from
// start_screen_data.hpp.
#pragma once
struct SDL_Renderer;
struct SDL_Texture;
+2
View File
@@ -1,4 +1,6 @@
// SPDX-License-Identifier: GPL-3.0-only
// Declares the embedded start screen artwork (JPEG bytes and their size); the definitions
// live in a separate data translation unit. Consumed only by start_screen.cpp.
#pragma once
#include <cstddef>
namespace bmh::app {
+3
View File
@@ -1,4 +1,7 @@
// SPDX-License-Identifier: GPL-3.0-only
// RAII guard for SDL video: SDL_Init(SDL_INIT_VIDEO) in the constructor (throws
// std::runtime_error on failure) and SDL_Quit in the destructor. It must exist before any
// native file picker is opened (see the comment on the class). Non-copyable, header-only.
#pragma once
#include <SDL.h>
#include <stdexcept>
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the club and league window facades declared in window_actions.hpp. Each
// method validates the UI request against the session state, runs it on the CareerSession
// inside an apply() transaction (state, RNG and revision are restored on rejection or an
// exception) and hands the result to the front end's acknowledgement callback. Errors come
// back through the std::string& error parameter; see controller.cpp for the overall model.
#include "formats/executable_layout.hpp"
#include "app/window_actions.hpp"
#include "app/action_transaction.hpp"
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Application-boundary facades for the club and league windows: league table/pairings/
// strengths, transfer market and offers, bank, stadium, desk actions and lineup. Same pattern
// as desktop_actions.hpp: a class per owner that wraps a CareerSession, offers apply() as a
// rollback transaction and takes the shared revision counter plus an acknowledgement
// callback from the front end. Implemented in window_actions.cpp, called from controller.cpp.
#pragma once
#include "app/career_session.hpp"