From 7179ea8b029ce9a516c6d5a0a04586235cd7bd2b Mon Sep 17 00:00:00 2001 From: Rito12 Date: Thu, 19 Feb 2026 13:03:59 +0100 Subject: [PATCH] Codechange: Fix all doxygen warnings related to train.h file. Fixes 14 doxygen warnings. The `head` parameter of `GroundVehicle::GetPoweredPartPower` virtual method is removed as it's always the same as the object it's called on. --- src/ground_vehicle.cpp | 2 +- src/ground_vehicle.hpp | 2 +- src/roadveh.h | 2 +- src/train.h | 31 +++++++++++++++++++------------ src/train_cmd.cpp | 4 ++++ 5 files changed, 26 insertions(+), 15 deletions(-) diff --git a/src/ground_vehicle.cpp b/src/ground_vehicle.cpp index 7962aa8277..8aa55605ef 100644 --- a/src/ground_vehicle.cpp +++ b/src/ground_vehicle.cpp @@ -29,7 +29,7 @@ void GroundVehicle::PowerChanged() uint16_t max_track_speed = this->vcache.cached_max_speed; // Max track speed in internal units. for (const T *u = v; u != nullptr; u = u->Next()) { - uint32_t current_power = u->GetPower() + u->GetPoweredPartPower(u); + uint32_t current_power = u->GetPower() + u->GetPoweredPartPower(); total_power += current_power; /* Only powered parts add tractive effort. */ diff --git a/src/ground_vehicle.hpp b/src/ground_vehicle.hpp index 9d3e93fa14..24914540d6 100644 --- a/src/ground_vehicle.hpp +++ b/src/ground_vehicle.hpp @@ -64,7 +64,7 @@ enum GroundVehicleFlags : uint8_t { * These functions are not defined as pure virtual functions at this class to improve performance. * * virtual uint16_t GetPower() const = 0; - * virtual uint16_t GetPoweredPartPower(const T *head) const = 0; + * virtual uint16_t GetPoweredPartPower() const = 0; * virtual uint16_t GetWeight() const = 0; * virtual uint8_t GetTractiveEffort() const = 0; * virtual uint8_t GetAirDrag() const = 0; diff --git a/src/roadveh.h b/src/roadveh.h index 3eea464d5c..4fb68159ec 100644 --- a/src/roadveh.h +++ b/src/roadveh.h @@ -159,7 +159,7 @@ protected: // These functions should not be called outside acceleration code. * Returns a value if this articulated part is powered. * @return Zero, because road vehicles don't have powered parts. */ - inline uint16_t GetPoweredPartPower(const RoadVehicle *) const + inline uint16_t GetPoweredPartPower() const { return 0; } diff --git a/src/train.h b/src/train.h index ee223c06e2..280f9fd193 100644 --- a/src/train.h +++ b/src/train.h @@ -32,6 +32,7 @@ enum class VehicleRailFlag : uint8_t { Stuck = 8, ///< Train can't get a path reservation. LeavingStation = 9, ///< Train is just leaving a station. }; +/** Bitset of the %VehicleRailFlag elements. */ using VehicleRailFlags = EnumBitSet; /** Modes for ignoring signals. */ @@ -46,7 +47,7 @@ enum class ConsistChangeFlag : uint8_t { Length, ///< Allow vehicles to change length. Capacity, ///< Allow vehicles to change capacity. }; - +/** Bitset of the %ConsistChangeFlag elements. */ using ConsistChangeFlags = EnumBitSet; static constexpr ConsistChangeFlags CCF_TRACK{}; ///< Valid changes while vehicle is driving, and possibly changing tracks. @@ -72,7 +73,7 @@ void NormalizeTrainVehInDepot(const Train *u); /** Variables that are cached to improve performance and such */ struct TrainCache { - /* Cached wagon override spritegroup */ + /** Cached wagon override spritegroup. */ const struct SpriteGroup *cached_override = nullptr; /* cached values, recalculated on load and each time a vehicle is added to/removed from the consist. */ @@ -82,28 +83,34 @@ struct TrainCache { int16_t cached_curve_speed_mod = 0; ///< curve speed modifier of the entire train uint16_t cached_max_curve_speed = 0; ///< max consist speed limited by curves - auto operator<=>(const TrainCache &) const = default; + /** + * Compare variables with another instance of this class. + * @param other The other instance of TrainCache. + * @return The std::strong_ordering of the comparison. + */ + auto operator<=>(const TrainCache &other) const = default; }; /** * 'Train' is either a loco or a wagon. */ struct Train final : public GroundVehicle { - VehicleRailFlags flags{}; + VehicleRailFlags flags{}; ///< Which flags has this train currently set. @see VehicleRailFlag for more details. uint16_t crash_anim_pos = 0; ///< Crash animation counter. uint16_t wait_counter = 0; ///< Ticks waiting in front of a signal, ticks being stuck or a counter for forced proceeding through signals. - TrainCache tcache{}; + TrainCache tcache{}; ///< Set of cached variables, recalculated on load and each time a vehicle is added to/removed from the consist. - /* Link between the two ends of a multiheaded engine */ + /** Link between the two ends of a multiheaded engine. */ Train *other_multiheaded_part = nullptr; - RailTypes compatible_railtypes{}; - RailTypes railtypes{}; + RailTypes compatible_railtypes{}; ///< With which rail types the train is compatible. + RailTypes railtypes{}; ///< On which rail types the train can run. - TrackBits track{}; - TrainForceProceeding force_proceed{}; + TrackBits track{}; ///< On which track the train currently is. + TrainForceProceeding force_proceed{}; ///< How the train should behave when it encounters next obstacle. + /** Create new Train object. @copydoc GroundVehicle::GroundVehicle */ Train(VehicleID index) : GroundVehicleBase(index) {} /** We want to 'destruct' the right class. */ ~Train() override { this->PreDestructor(); } @@ -211,10 +218,10 @@ protected: // These functions should not be called outside acceleration code. * Returns a value if this articulated part is powered. * @return Power value from the articulated part in HP, or zero if it is not powered. */ - inline uint16_t GetPoweredPartPower(const Train *head) const + inline uint16_t GetPoweredPartPower() const { /* For powered wagons the engine defines the type of engine (i.e. railtype) */ - if (this->flags.Test(VehicleRailFlag::PoweredWagon) && HasPowerOnRail(head->railtypes, GetRailType(this->tile))) { + if (this->flags.Test(VehicleRailFlag::PoweredWagon) && HasPowerOnRail(this->railtypes, GetRailType(this->tile))) { return RailVehInfo(this->gcache.first_engine)->pow_wag_power; } diff --git a/src/train_cmd.cpp b/src/train_cmd.cpp index 0c00f1cc74..efccdcade5 100644 --- a/src/train_cmd.cpp +++ b/src/train_cmd.cpp @@ -437,6 +437,10 @@ void Train::UpdateAcceleration() this->acceleration = Clamp(power / weight * 4, 1, 255); } +/** + * Get the offset for train image when it is used as cursor. + * @return The offset in horizontal direction. + */ int Train::GetCursorImageOffset() const { if (this->gcache.cached_veh_length != 8 && this->flags.Test(VehicleRailFlag::Flipped) && !EngInfo(this->engine_type)->misc_flags.Test(EngineMiscFlag::RailFlips)) {