From 8303b2d694021e0dabacaaeb8a8efbf2ac70f8da Mon Sep 17 00:00:00 2001 From: Rubidium Date: Wed, 1 Jul 2026 21:27:29 +0200 Subject: [PATCH] Codechange: document gamelog_internal.h --- src/gamelog_internal.h | 93 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 3 deletions(-) diff --git a/src/gamelog_internal.h b/src/gamelog_internal.h index 80df95b134..af746f91bc 100644 --- a/src/gamelog_internal.h +++ b/src/gamelog_internal.h @@ -25,13 +25,25 @@ struct GRFPresence { const GRFConfig *gc = nullptr; ///< GRFConfig, if known bool was_missing = false; ///< Grf was missing during some gameload in the past + /** + * Create the presence. + * @param gc The configuration of the NewGRF. + */ GRFPresence(const GRFConfig *gc) : gc(gc) {} + + /** Create an empty presence. */ GRFPresence() = default; }; -using GrfIDMapping = std::map; +using GrfIDMapping = std::map; ///< A mapping from \c GRFID to the \c GRFPresence. +/** Container for any change that we deem needs to be logged. */ struct LoggedChange { + /** + * Create the log entry. + * @param type The type of change to log. + */ LoggedChange(GamelogChangeType type = GamelogChangeType::None) : ct(type) {} + /** Ensure the destructor of the sub classes are called as well. */ virtual ~LoggedChange() = default; @@ -43,7 +55,7 @@ struct LoggedChange { */ virtual void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) = 0; - GamelogChangeType ct{}; + GamelogChangeType ct{}; ///< The type of change. }; /** Log element for the change of the game mode and landscape. */ @@ -64,8 +76,18 @@ struct LoggedChangeMode : LoggedChange { LandscapeType landscape{}; ///< landscape (temperate, arctic, ...) }; +/** A log entry for a change in OpenTTD version. */ struct LoggedChangeRevision : LoggedChange { + /** Constructor for savegame loading. */ LoggedChangeRevision() : LoggedChange(GamelogChangeType::Revision) {} + + /** + * Create the new log entry. + * @param text The string representation of the version. + * @param newgrf The NewGRF version. + * @param slver The savegame version. + * @param modified Whether the executable was modified. + */ LoggedChangeRevision(const std::string &text, uint32_t newgrf, uint16_t slver, uint8_t modified) : LoggedChange(GamelogChangeType::Revision), text(text), newgrf(newgrf), slver(slver), modified(modified) {} void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) override; @@ -76,8 +98,16 @@ struct LoggedChangeRevision : LoggedChange { uint8_t modified = 0; ///< _openttd_revision_modified }; +/** A log entry for loading a really old savegame. */ struct LoggedChangeOldVersion : LoggedChange { + /** Constructor for savegame loading. */ LoggedChangeOldVersion() : LoggedChange(GamelogChangeType::OldVer) {} + + /** + * Create the entry. + * @param type The \c SavegameType. + * @param version The TTDP or ancient OpenTTD version if available. + */ LoggedChangeOldVersion(uint32_t type, uint32_t version) : LoggedChange(GamelogChangeType::OldVer), type(type), version(version) {} void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) override; @@ -86,15 +116,29 @@ struct LoggedChangeOldVersion : LoggedChange { uint32_t version = 0; ///< major and minor version OR ttdp version }; +/** A log entry for a NewGRF that was added. */ struct LoggedChangeGRFAdd : LoggedChange, GRFIdentifier { + /** Constructor for savegame loading. */ LoggedChangeGRFAdd() : LoggedChange(GamelogChangeType::GRFAdd) {} + + /** + * Create a log entry for an added NewGRF. + * @param ident The NewGRF that is added. + */ LoggedChangeGRFAdd(const GRFIdentifier &ident) : LoggedChange(GamelogChangeType::GRFAdd), GRFIdentifier(ident) {} void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) override; }; +/** A log entry for a NewGRF that was removed. */ struct LoggedChangeGRFRemoved : LoggedChange { + /** Constructor for savegame loading. */ LoggedChangeGRFRemoved() : LoggedChange(GamelogChangeType::GRFRem) {} + + /** + * Create a log entry for a removed NewGRF. + * @param grfid The NewGRF that is removed. + */ LoggedChangeGRFRemoved(uint32_t grfid) : LoggedChange(GamelogChangeType::GRFRem), grfid(grfid) {} void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) override; @@ -102,15 +146,29 @@ struct LoggedChangeGRFRemoved : LoggedChange { uint32_t grfid = 0; ///< ID of removed GRF }; +/** A log entry for a NewGRF that was changed. */ struct LoggedChangeGRFChanged : LoggedChange, GRFIdentifier { + /** Constructor for savegame loading. */ LoggedChangeGRFChanged() : LoggedChange(GamelogChangeType::GRFCompat) {} + + /** + * Create a log entry for a changed NewGRF. + * @param ident The NewGRF that is changed. + */ LoggedChangeGRFChanged(const GRFIdentifier &ident) : LoggedChange(GamelogChangeType::GRFCompat), GRFIdentifier(ident) {} void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) override; }; +/** A log entry for a NewGRF for which a parameter was changed. */ struct LoggedChangeGRFParameterChanged : LoggedChange { + /** Constructor for savegame loading. */ LoggedChangeGRFParameterChanged() : LoggedChange(GamelogChangeType::GRFParam) {} + + /** + * Create a log entry for a parameter change of a NewGRF. + * @param grfid The NewGRF for which the parameter is changed. + */ LoggedChangeGRFParameterChanged(uint32_t grfid) : LoggedChange(GamelogChangeType::GRFParam), grfid(grfid) {} void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) override; @@ -118,8 +176,16 @@ struct LoggedChangeGRFParameterChanged : LoggedChange { uint32_t grfid = 0; ///< ID of GRF with changed parameters }; +/** A log entry for a NewGRF that was moved. */ struct LoggedChangeGRFMoved : LoggedChange { + /** Constructor for savegame loading. */ LoggedChangeGRFMoved() : LoggedChange(GamelogChangeType::GRFMove) {} + + /** + * Create a log entry for a moved NewGRF. + * @param grfid The NewGRF that is moved. + * @param offset The amount the NewGRF was moved. + */ LoggedChangeGRFMoved(uint32_t grfid, int32_t offset) : LoggedChange(GamelogChangeType::GRFMove), grfid(grfid), offset(offset) {} void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) override; @@ -128,8 +194,17 @@ struct LoggedChangeGRFMoved : LoggedChange { int32_t offset = 0; ///< offset, positive = move down }; +/** A log entry for changing a setting. */ struct LoggedChangeSettingChanged : LoggedChange { + /** Constructor for savegame loading. */ LoggedChangeSettingChanged() : LoggedChange(GamelogChangeType::Setting) {} + + /** + * Create the log entry. + * @param name The name of the setting. + * @param oldval The value before the change. + * @param newval The value after the change. + */ LoggedChangeSettingChanged(const std::string &name, int32_t oldval, int32_t newval) : LoggedChange(GamelogChangeType::Setting), name(name), oldval(oldval), newval(newval) {} void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) override; @@ -139,8 +214,17 @@ struct LoggedChangeSettingChanged : LoggedChange { int32_t newval = 0; ///< new value }; +/** A log entry for a NewGRF bug. */ struct LoggedChangeGRFBug : LoggedChange { + /** Constructor for savegame loading. */ LoggedChangeGRFBug() : LoggedChange(GamelogChangeType::GRFBug) {} + + /** + * Create a NewGRF bug log entry. + * @param data Bug specific extra data for identifying the buggy entry. + * @param grfid The NewGRF that is deemed buggy. + * @param bug The bug that has been seen. + */ LoggedChangeGRFBug(uint64_t data, uint32_t grfid, GRFBug bug) : LoggedChange(GamelogChangeType::GRFBug), data(data), grfid(grfid), bug(bug) {} void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) override; @@ -150,7 +234,9 @@ struct LoggedChangeGRFBug : LoggedChange { GRFBug bug{}; ///< type of bug, @see enum GRFBugs }; +/** A log entry denoting that this savegame was involved in an emergency (crash) save. */ struct LoggedChangeEmergencySave : LoggedChange { + /** Create the entry. */ LoggedChangeEmergencySave() : LoggedChange(GamelogChangeType::Emergency) {} void FormatTo(std::back_insert_iterator &output_iterator, GrfIDMapping &grf_names, GamelogActionType action_type) override; }; @@ -163,8 +249,9 @@ struct LoggedAction { uint64_t tick = 0; ///< Tick when it happened }; +/** Container for some internal data. */ struct GamelogInternalData { - std::vector action; + std::vector action; ///< The known actions. }; #endif /* GAMELOG_INTERNAL_H */