diff --git a/src/effectvehicle_base.h b/src/effectvehicle_base.h index 11067db618..4cd31988be 100644 --- a/src/effectvehicle_base.h +++ b/src/effectvehicle_base.h @@ -23,8 +23,8 @@ * - bubbles (industry) */ struct EffectVehicle : public SpecializedVehicle { - uint16 animation_state; - byte animation_substate; + uint16 animation_state; ///< State primarily used to change the graphics/behaviour. + byte animation_substate; ///< Sub state to time the change of the graphics/behaviour. /** We don't want GCC to zero our struct! It already is zeroed and has an index! */ EffectVehicle() : SpecializedVehicleBase() {} @@ -35,6 +35,10 @@ struct EffectVehicle : public SpecializedVehicle { bool Tick(); }; +/** + * Iterate over disaster vehicles. + * @param var The variable used to iterate over. + */ #define FOR_ALL_EFFECTVEHICLES(var) FOR_ALL_VEHICLES_OF_TYPE(EffectVehicle, var) #endif /* EFFECTVEHICLE_BASE_H */ diff --git a/src/saveload/afterload.cpp b/src/saveload/afterload.cpp index 679b0244f5..35a5579baa 100644 --- a/src/saveload/afterload.cpp +++ b/src/saveload/afterload.cpp @@ -473,6 +473,11 @@ static uint FixVehicleInclination(Vehicle *v, Direction dir) return 1U << GVF_GOINGUP_BIT; } +/** + * Perform a (large) amount of savegame conversion *magic* in order to + * load older savegames and to fill the caches for various purposes. + * @return True iff conversion went without a problem. + */ bool AfterLoadGame() { SetSignalHandlers(); diff --git a/src/saveload/oldloader_sl.cpp b/src/saveload/oldloader_sl.cpp index f6572cd8fb..e846c1ce5f 100644 --- a/src/saveload/oldloader_sl.cpp +++ b/src/saveload/oldloader_sl.cpp @@ -163,6 +163,11 @@ static void FixOldTowns() static StringID *_old_vehicle_names; +/** + * Convert the old style vehicles into something that resembles + * the old new style savegames. Then #AfterLoadGame can handle + * the rest of the conversion. + */ void FixOldVehicles() { Vehicle *v; @@ -1212,6 +1217,12 @@ static const OldChunks vehicle_chunk[] = { OCL_END() }; +/** + * Load the vehicles of an old style savegame. + * @param ls State (buffer) of the currently loaded game. + * @param num The number of vehicles to load. + * @return True iff loading went without problems. + */ bool LoadOldVehicle(LoadgameState *ls, int num) { /* Read the TTDPatch flags, because we need some info from it */ diff --git a/src/saveload/vehicle_sl.cpp b/src/saveload/vehicle_sl.cpp index 61dece3800..8abcb916b9 100644 --- a/src/saveload/vehicle_sl.cpp +++ b/src/saveload/vehicle_sl.cpp @@ -22,7 +22,7 @@ #include -/* +/** * Link front and rear multiheaded engines to each other * This is done when loading a savegame */ diff --git a/src/vehicle.cpp b/src/vehicle.cpp index d2e4556d48..50aa1c5c5c 100644 --- a/src/vehicle.cpp +++ b/src/vehicle.cpp @@ -63,7 +63,7 @@ uint16 _returned_mail_refit_capacity; ///< Stores the mail capacity after a refi byte _age_cargo_skip_counter; ///< Skip aging of cargo? -/* Initialize the vehicle-pool */ +/** The pool with all our precious vehicles. */ VehiclePool _vehicle_pool("Vehicle"); INSTANTIATE_POOL_METHODS(Vehicle) @@ -1805,9 +1805,13 @@ void Vehicle::DeleteUnreachedAutoOrders() } } +/** + * Prepare everything to begin the loading when arriving at a station. + * @pre IsTileType(this->tile, MP_STATION) || this->type == VEH_SHIP. + */ void Vehicle::BeginLoading() { - assert(IsTileType(tile, MP_STATION) || type == VEH_SHIP); + assert(IsTileType(this->tile, MP_STATION) || this->type == VEH_SHIP); if (this->current_order.IsType(OT_GOTO_STATION) && this->current_order.GetDestination() == this->last_station_visited) { @@ -1854,16 +1858,20 @@ void Vehicle::BeginLoading() this->MarkDirty(); } +/** + * Perform all actions when leaving a station. + * @pre this->current_order.IsType(OT_LOADING) + */ void Vehicle::LeaveStation() { - assert(current_order.IsType(OT_LOADING)); + assert(this->current_order.IsType(OT_LOADING)); delete this->cargo_payment; /* Only update the timetable if the vehicle was supposed to stop here. */ - if (current_order.GetNonStopType() != ONSF_STOP_EVERYWHERE) UpdateVehicleTimetable(this, false); + if (this->current_order.GetNonStopType() != ONSF_STOP_EVERYWHERE) UpdateVehicleTimetable(this, false); - current_order.MakeLeaveStation(); + this->current_order.MakeLeaveStation(); Station *st = Station::Get(this->last_station_visited); st->loading_vehicles.remove(this); diff --git a/src/vehicle_base.h b/src/vehicle_base.h index c5290e7705..623f534fbe 100644 --- a/src/vehicle_base.h +++ b/src/vehicle_base.h @@ -156,27 +156,29 @@ public: int32 lateness_counter; ///< How many ticks late (or early if negative) this vehicle is. Date timetable_start; ///< When the vehicle is supposed to start the timetable. - /* Boundaries for the current position in the world and a next hash link. - * NOSAVE: All of those can be updated with VehiclePositionChanged() */ - Rect coord; - Vehicle *next_hash, **prev_hash; - Vehicle *next_new_hash, **prev_new_hash; - Vehicle **old_new_hash; + Rect coord; ///< NOSAVE: Graphical bounding box of the vehicle, i.e. what to redraw on moves. + + Vehicle *next_hash; ///< NOSAVE: Next vehicle in the visual location hash. + Vehicle **prev_hash; ///< NOSAVE: Previous vehicle in the visual location hash. + + Vehicle *next_new_hash; ///< NOSAVE: Next vehicle in the tile location hash. + Vehicle **prev_new_hash; ///< NOSAVE: Previous vehicle in the tile location hash. + Vehicle **old_new_hash; ///< NOSAVE: Cache of the current hash chain. SpriteID colourmap; ///< NOSAVE: cached colour mapping /* Related to age and service time */ - Year build_year; + Year build_year; ///< Year the vehicle has been built. Date age; ///< Age in days Date max_age; ///< Maximum age - Date date_of_last_service; - Date service_interval; + Date date_of_last_service; ///< Last date the vehicle had a service at a depot. + Date service_interval; ///< The interval for (automatic) servicing; either in days or %. uint16 reliability; ///< Reliability. uint16 reliability_spd_dec; ///< Reliability decrease speed. byte breakdown_ctr; ///< Counter for managing breakdown events. @see Vehicle::HandleBreakdown byte breakdown_delay; ///< Counter for managing breakdown length. - byte breakdowns_since_last_service; - byte breakdown_chance; + byte breakdowns_since_last_service; ///< Counter for the amount of breakdowns. + byte breakdown_chance; ///< Current chance of breakdowns. int32 x_pos; ///< x coordinate. int32 y_pos; ///< y coordinate. @@ -193,7 +195,7 @@ public: byte z_extent; ///< z-extent of vehicle bounding box int8 x_offs; ///< x offset for vehicle sprite int8 y_offs; ///< y offset for vehicle sprite - EngineID engine_type; + EngineID engine_type; ///< The type of engine used for this vehicle. TextEffectID fill_percent_te_id; ///< a text-effect id to a loading indicator object UnitID unitnumber; ///< unit number, for display purposes only @@ -201,16 +203,13 @@ public: uint16 cur_speed; ///< current speed byte subspeed; ///< fractional speed byte acceleration; ///< used by train & aircraft - uint32 motion_counter; - byte progress; + uint32 motion_counter; ///< counter to occasionally play a vehicle sound. + byte progress; ///< The percentage (if divided by 256) this vehicle already crossed the tile unit. - /* for randomized variational spritegroups - * bitmask used to resolve them; parts of it get reseeded when triggers - * of corresponding spritegroups get matched */ - byte random_bits; - byte waiting_triggers; ///< triggers to be yet matched + byte random_bits; ///< Bits used for determining which randomized variational spritegroups to use when drawing. + byte waiting_triggers; ///< Triggers to be yet matched before rerandomizing the random bits. - StationID last_station_visited; + StationID last_station_visited; ///< The last station we stopped at. CargoID cargo_type; ///< type of cargo this vehicle is carrying byte cargo_subtype; ///< Used for livery refits (NewGRF variations) @@ -228,15 +227,12 @@ public: union { OrderList *list; ///< Pointer to the order list for this vehicle Order *old; ///< Only used during conversion of old save games - } orders; + } orders; ///< The orders currently assigned to the vehicle. byte vehicle_flags; ///< Used for gradual loading and other miscellaneous things (@see VehicleFlags enum) - /** Ticks to wait before starting next cycle. */ - uint16 load_unload_ticks; - + uint16 load_unload_ticks; ///< Ticks to wait before starting next cycle. GroupID group_id; ///< Index of group Pool array - byte subtype; ///< subtype (Filled with values from #EffectVehicles/#TrainSubTypes/#AircraftSubTypes) NewGRFCache grf_cache; ///< Cache of often used calculated NewGRF values @@ -736,7 +732,17 @@ public: } }; +/** + * Iterate over all vehicles from a given point. + * @param var The variable used to iterate over. + * @param start The vehicle to start the iteration at. + */ #define FOR_ALL_VEHICLES_FROM(var, start) FOR_ALL_ITEMS_FROM(Vehicle, vehicle_index, var, start) + +/** + * Iterate over all vehicles. + * @param var The variable used to iterate over. + */ #define FOR_ALL_VEHICLES(var) FOR_ALL_VEHICLES_FROM(var, 0) /** @@ -896,14 +902,19 @@ struct SpecializedVehicle : public Vehicle { } }; +/** + * Iterate over all vehicles of a particular type. + * @param name The type of vehicle to iterate over. + * @param var The variable used to iterate over. + */ #define FOR_ALL_VEHICLES_OF_TYPE(name, var) FOR_ALL_ITEMS_FROM(name, vehicle_index, var, 0) if (var->type == name::EXPECTED_TYPE) /** * Disasters, like submarines, skyrangers and their shadows, belong to this class. */ struct DisasterVehicle : public SpecializedVehicle { - uint16 image_override; - VehicleID big_ufo_destroyer_target; + SpriteID image_override; ///< Override for the default disaster vehicle sprite. + VehicleID big_ufo_destroyer_target; ///< The big UFO that this destroyer is supposed to bomb. /** We don't want GCC to zero our struct! It already is zeroed and has an index! */ DisasterVehicle() : SpecializedVehicleBase() {} @@ -914,6 +925,10 @@ struct DisasterVehicle : public SpecializedVehiclecache); } }; +/** Sentinel for an invalid coordinate. */ static const int32 INVALID_COORD = 0x7fffffff; #endif /* VEHICLE_BASE_H */