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
// Decides which club badge tokens the original draws as a fallback instead of an individual
// crest. The cut-off for foreign clubs differs between game editions, so it is read from one
// instruction in the loaded executable (layout::ForeignBadgeGateInstruction) and stored in the
// process-wide original_foreign_badge_end by install_original_badge_policy(). An executable
// that does not match the verified pattern falls back to 138. Header-only; the club
// selectors themselves stay in the database and savegame data.
#pragma once
#include "formats/executable_layout.hpp"
+4
View File
@@ -1,4 +1,8 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the basic file helpers declared in binary.hpp: read_file() loads a whole
// file into a Bytes vector (FormatError if it cannot be opened) and iso646de_to_utf8()
// converts the game's ISO 646-DE strings ([ \ ] { | } ~ stand for the umlauts and the sharp s)
// to UTF-8. No state.
#include "formats/binary.hpp"
#include <fstream>
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the .FBM savegame container (fbm.hpp): fbm_encrypt()/fbm_decrypt() are the
// stream cipher whose key changes by 0x29 per byte, and load_savegame() finds the "KRON_FBM"
// magic, splits the plain header from the encrypted stream, decrypts it and verifies the
// one-byte checksum, which is reported in Savegame::checksum_ok (not thrown). The decrypted
// stream is interpreted by savestate.cpp. Pure functions, no state.
#include "formats/fbm.hpp"
#include <algorithm>
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the .FNT bitmap font loader and renderer (font.hpp): load_font() reads
// the header, the 1-bit glyph bitmap and the per-character location (and spacing) tables and
// checks that the file size matches exactly; Font::glyph(), text_width() and draw() look up
// glyphs (out-of-range characters use the last glyph) and draw them into an indexed Image.
// No state beyond the Font object.
#include "formats/font.hpp"
namespace bmh {
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the executable image loader (le.hpp): load_le() reads the original
// DOS/4GW LE executable, places its objects at their link addresses and applies the internal
// fixups (FormatError for other files or external fixups). It also accepts the OpenBMH image
// format written by save_image(), so a translated image can replace the executable.
// LeImage::cstring() reads NUL-terminated strings from the image. No global state.
#include "formats/le.hpp"
#include <algorithm>
+4
View File
@@ -1,4 +1,8 @@
// SPDX-License-Identifier: GPL-3.0-only
// Reads from the loaded executable how many league levels a player can see; the original
// separates internal domestic league slots from these visible levels. Throws
// std::invalid_argument when the stored constants fail the sanity check. Header-only,
// stateless; the address comes from executable_layout.hpp and the image from le.hpp.
#pragma once
#include "formats/executable_layout.hpp"
#include "formats/le.hpp"
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the M3D.MAN master database loader (m3d.hpp). load_database() reads the
// file sequentially with a bounds-checked Reader: first the lengths of the four string pools
// (clubs, players, referees, stadiums), then the pools, the name offset tables and the raw
// record blocks, whose sizes depend on the DbCounts passed in. Several blocks are kept as raw
// bytes in the Database (raw_* fields). Throws FormatError on a truncated file.
#include "formats/m3d.hpp"
#include <cstring>
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Accepted savegame version markers for the native (original-layout) save format. The FBM
// container (fbm.hpp) carries a version string; V2.24 and V3.7 share the same block order,
// while expanded careers use their own marker (O1.1) and layout. require_native_savegame()
// throws FormatError on a bad checksum or an unsupported marker; callers still validate the
// full state layout afterwards (savestate.hpp). Header-only.
#pragma once
#include "formats/fbm.hpp"
#include <string_view>
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the palette loader (palette.hpp). load_palette() reads a 256-entry,
// 6 bits per channel RGB file and converts it to 32-bit ARGB via vga_dac_rgb8();
// load_optional_embedded_palette() reads the palette that may follow the RLE data of a VGA
// image file (std::nullopt if there is none); Palette::nearest() returns the index of the
// closest colour by squared RGB distance. FormatError on short or inconsistent files.
#include "formats/palette.hpp"
#include "formats/binary.hpp"
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the savegame stream layout (savestate.hpp). save_layout() lists the
// blocks in the exact order the original wrote them, with sizes that are constants or depend
// on DbCounts; the SaveState constructor splits a decrypted stream along that list, reads
// the four string-pool trailer blocks and the optional OpenBMH extension, and throws
// FormatError if the sizes do not add up. append_save_extension() writes that extension.
#include "formats/executable_layout.hpp"
#include "formats/savestate.hpp"
+3
View File
@@ -1,4 +1,7 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the TEXTD.BLK loader (textd.hpp): skips the 7-byte header, keeps the whole
// blob and splits it into NUL-terminated strings, recording each string's offset. Exactly
// TEXT_COUNT strings must be found, otherwise FormatError. No state.
#include "formats/textd.hpp"
#include "formats/binary.hpp"
+4
View File
@@ -1,4 +1,8 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the .VGA image support (vga.hpp): Image::blit() copies one indexed image
// into another with clipping, decode_vga() unpacks the run-length data (a byte of 0x80 or
// more is a run, below that a literal block) and checks the length fields and the single
// trailing byte, and load_vga() reads a file and decodes it. FormatError on malformed data.
#include "formats/vga.hpp"
namespace bmh {