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

+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the console line parser (parser.hpp): trimming, top-level splitting of
// the argument list (commas inside quotes or brackets do not split), parsing of one
// argument (positional or name=value), canonical name comparison that ignores case, '.' and
// '_', line classification, and the integer/bool converters for arguments. Pure functions;
// no console state. The console (console.cpp, windows_*.cpp) checks the argument types.
#include "cli/console/parser.hpp"
#include <cctype>
+4
View File
@@ -1,4 +1,8 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of parse_json()/dump_json() (json.hpp): a small recursive-descent Parser
// over a string_view that reports the byte position in JsonError messages, UTF-8 handling
// for string escapes, and a serializer for the Json variant. No state beyond the parser's
// position in the input.
#include "cli/json.hpp"
#include <charconv>
+5
View File
@@ -1,4 +1,9 @@
// SPDX-License-Identifier: GPL-3.0-only
// Minimal JSON value type for the CLI protocol (no external library). A Json holds null,
// bool, a 64-bit integer, string, array or object (std::map) in one std::variant; the
// accessors return null pointers when the type does not match, so callers must check.
// Numbers are integers only. parse_json() throws JsonError on bad input; dump_json() writes
// compact text. Used by protocol.*, seat_hub.cpp and main.cpp; implemented in json.cpp.
#pragma once
#include <cstdint>
+7
View File
@@ -1,4 +1,11 @@
// SPDX-License-Identifier: GPL-3.0-only
// Entry point of openbmh_cli, the headless front end without a window. Besides parsing the
// command line (Arguments) it offers several modes on top of the same engine: the JSON
// protocol on stdin/stdout (protocol.hpp) with --log/--replay, the console language
// (docs/CLI_CONCEPT) as plain session, replay, mailbox server (--serve), multi-seat server
// (--seats, SeatHub), TCP listener on 127.0.0.1 (--listen), and --send to hand one block to
// a running mailbox session. --data may be a game directory, the game's EXE or an archive
// (src/launch resolves it). All game logic stays in the engine; this file only moves lines.
#include "cli/protocol.hpp"
#include "cli/console/console.hpp"
#include "cli/seat_hub.hpp"
+7
View File
@@ -1,4 +1,11 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of the JSON protocol (protocol.hpp). Protocol::handle() validates the
// request keys per command (check_keys / check_command_keys), then calls the CareerSession
// and the same projection functions the SDL front end uses (desk, table, mail, tactics,
// training, camp, bank, stadium, kickoff, save/load, ...), and wraps the result with the
// current revision. Errors are returned as {"ok": false, "error": ...}, never thrown to the
// caller. The "replay" flag lets a logged session be played again (saves may overwrite).
// text_request()/text_response() implement the one-line text form of the protocol.
#include "formats/executable_layout.hpp"
#include "cli/protocol.hpp"
+6
View File
@@ -1,4 +1,10 @@
// SPDX-License-Identifier: GPL-3.0-only
// The JSON line protocol of openbmh_cli (the non-console mode): one request object with a
// "cmd" field in, one response object ("ok", "revision", result or error) out. Protocol owns
// one app::CareerSession (created by "new" or "load") and the revision counter that every
// state-changing command must echo back, so stale requests are refused like in the UI
// flow. text_request()/text_response() translate a simple one-line text form to and from the
// same JSON. Implemented in protocol.cpp; Protocol::help() lists the commands.
#pragma once
#include "cli/json.hpp"
+6
View File
@@ -1,4 +1,10 @@
// SPDX-License-Identifier: GPL-3.0-only
// Implementation of SeatHub (seat_hub.hpp): routes the blocks of several clients into one
// console::Console. It runs a block as the seat's manager ("@k"), classifies each output
// line with Console::LineInfo, queues lines that concern other seats as their "meanwhile"
// feed, holds WaitTurn blocks until they can be answered, and holds the Run/Step of a live
// match until every seat has sent one. State per seat is a small Seat record; the game
// itself lives in the console.
#include "cli/seat_hub.hpp"
#include <algorithm>