From 07e14525b8fdf1e9adcc81af117aa8bf5d3d167a Mon Sep 17 00:00:00 2001 From: rubidium Date: Wed, 19 Jan 2011 16:20:26 +0000 Subject: (svn r21848) -Codechange: unification of comment style for cargopacket.* --- src/cargopacket.cpp | 109 ++++++++++++++++++++++--------------------- src/cargopacket.h | 130 ++++++++++++++++++++++++++-------------------------- 2 files changed, 122 insertions(+), 117 deletions(-) diff --git a/src/cargopacket.cpp b/src/cargopacket.cpp index e73341ff3..732d9fd1d 100644 --- a/src/cargopacket.cpp +++ b/src/cargopacket.cpp @@ -7,7 +7,7 @@ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see . */ -/** @file cargopacket.cpp Implementation of the cargo packets */ +/** @file cargopacket.cpp Implementation of the cargo packets. */ #include "stdafx.h" #include "core/pool_func.hpp" @@ -35,12 +35,12 @@ CargoPacket::CargoPacket() } /** - * Creates a new cargo packet - * @param source the source station of the packet - * @param source_xy the source location of the packet - * @param count the number of cargo entities to put in this packet - * @param source_type the 'type' of source the packet comes from (for subsidies) - * @param source_id the actual source of the packet (for subsidies) + * Creates a new cargo packet. + * @param source Source station of the packet. + * @param source_xy Source location of the packet. + * @param count Number of cargo entities to put in this packet. + * @param source_type 'Type' of source the packet comes from (for subsidies). + * @param source_id Actual source of the packet (for subsidies). * @pre count != 0 * @note We have to zero memory ourselves here because we are using a 'new' * that, in contrary to all other pools, does not memset to 0. @@ -61,14 +61,16 @@ CargoPacket::CargoPacket(StationID source, TileIndex source_xy, uint16 count, So /** * Creates a new cargo packet. Initializes the fields that cannot be changed later. * Used when loading or splitting packets. - * @param count the number of cargo entities to put in this packet - * @param days_in_transit number of days the cargo has been in transit - * @param source the station the cargo was initially loaded - * @param source_xy the station location the cargo was initially loaded - * @param loaded_at_xy the location the cargo was loaded last - * @param feeder_share feeder share the packet has already accumulated - * @param source_type the 'type' of source the packet comes from (for subsidies) - * @param source_id the actual source of the packet (for subsidies) + * @param count Number of cargo entities to put in this packet. + * @param days_in_transit Number of days the cargo has been in transit. + * @param source Station the cargo was initially loaded. + * @param source_xy Station location the cargo was initially loaded. + * @param loaded_at_xy Location the cargo was loaded last. + * @param feeder_share Feeder share the packet has already accumulated. + * @param source_type 'Type' of source the packet comes from (for subsidies). + * @param source_id Actual source of the packet (for subsidies). + * @note We have to zero memory ourselves here because we are using a 'new' + * that, in contrary to all other pools, does not memset to 0. */ CargoPacket::CargoPacket(uint16 count, byte days_in_transit, StationID source, TileIndex source_xy, TileIndex loaded_at_xy, Money feeder_share, SourceType source_type, SourceID source_id) : feeder_share(feeder_share), @@ -84,9 +86,9 @@ CargoPacket::CargoPacket(uint16 count, byte days_in_transit, StationID source, T } /** - * Invalidates (sets source_id to INVALID_SOURCE) all cargo packets from given source - * @param src_type type of source - * @param src index of source + * Invalidates (sets source_id to INVALID_SOURCE) all cargo packets from given source. + * @param src_type Type of source. + * @param src Index of source. */ /* static */ void CargoPacket::InvalidateAllFrom(SourceType src_type, SourceID src) { @@ -97,8 +99,8 @@ CargoPacket::CargoPacket(uint16 count, byte days_in_transit, StationID source, T } /** - * Invalidates (sets source to INVALID_STATION) all cargo packets from given station - * @param sid the station that gets removed + * Invalidates (sets source to INVALID_STATION) all cargo packets from given station. + * @param sid Station that gets removed. */ /* static */ void CargoPacket::InvalidateAllFrom(StationID sid) { @@ -114,7 +116,9 @@ CargoPacket::CargoPacket(uint16 count, byte days_in_transit, StationID source, T * */ -/** Destroy it ("frees" all cargo packets) */ +/** + * Destroy the cargolist ("frees" all cargo packets). + */ template CargoList::~CargoList() { @@ -125,8 +129,8 @@ CargoList::~CargoList() /** * Update the cached values to reflect the removal of this packet. - * Decreases count and days_in_transit - * @param cp Packet to be removed from cache + * Decreases count and days_in_transit. + * @param cp Packet to be removed from cache. */ template void CargoList::RemoveFromCache(const CargoPacket *cp) @@ -137,8 +141,8 @@ void CargoList::RemoveFromCache(const CargoPacket *cp) /** * Update the cache to reflect adding of this packet. - * Increases count and days_in_transit - * @param cp a new packet to be inserted + * Increases count and days_in_transit. + * @param cp New packet to be inserted. */ template void CargoList::AddToCache(const CargoPacket *cp) @@ -148,10 +152,11 @@ void CargoList::AddToCache(const CargoPacket *cp) } /** - * Appends the given cargo packet + * Appends the given cargo packet. Tries to merge it with another one in the + * packets list. If no fitting packet is found, appends it. * @warning After appending this packet may not exist anymore! * @note Do not use the cargo packet anymore after it has been appended to this CargoList! - * @param cp the cargo packet to add + * @param cp Cargo packet to add. * @pre cp != NULL */ template @@ -175,11 +180,10 @@ void CargoList::Append(CargoPacket *cp) this->packets.push_back(cp); } - /** * Truncates the cargo in this list to the given amount. It leaves the * first count cargo entities and removes the rest. - * @param max_remaining the maximum amount of entities to be in the list after the command + * @param max_remaining Maximum amount of entities to be in the list after the command. */ template void CargoList::Truncate(uint max_remaining) @@ -211,23 +215,23 @@ void CargoList::Truncate(uint max_remaining) /** * Moves the given amount of cargo to another list. * Depending on the value of mta the side effects of this function differ: - * - MTA_FINAL_DELIVERY: destroys the packets that do not originate from a specific station - * - MTA_CARGO_LOAD: sets the loaded_at_xy value of the moved packets - * - MTA_TRANSFER: just move without side effects - * - MTA_UNLOAD: just move without side effects - * @param dest the destination to move the cargo to - * @param count the amount of cargo entities to move - * @param mta how to handle the moving (side effects) + * - MTA_FINAL_DELIVERY: Destroys the packets that do not originate from a specific station. + * - MTA_CARGO_LOAD: Sets the loaded_at_xy value of the moved packets. + * - MTA_TRANSFER: Just move without side effects. + * - MTA_UNLOAD: Just move without side effects. + * @param dest Destination to move the cargo to. + * @param count Amount of cargo entities to move. + * @param mta How to handle the moving (side effects). * @param data Depending on mta the data of this variable differs: - * - MTA_FINAL_DELIVERY - station ID of packet's origin not to remove - * - MTA_CARGO_LOAD - station's tile index of load - * - MTA_TRANSFER - unused - * - MTA_UNLOAD - unused - * @param payment The payment helper + * - MTA_FINAL_DELIVERY - Station ID of packet's origin not to remove. + * - MTA_CARGO_LOAD - Station's tile index of load. + * - MTA_TRANSFER - Unused. + * - MTA_UNLOAD - Unused. + * @param payment The payment helper. * * @pre mta == MTA_FINAL_DELIVERY || dest != NULL * @pre mta == MTA_UNLOAD || mta == MTA_CARGO_LOAD || payment != NULL - * @return true if there are still packets that might be moved from this cargo list + * @return True if there are still packets that might be moved from this cargo list. */ template template @@ -308,7 +312,7 @@ bool CargoList::MoveTo(Tother_inst *dest, uint max_move, MoveToAction mta return it != packets.end(); } -/** Invalidates the cached data and rebuild it */ +/** Invalidates the cached data and rebuilds it. */ template void CargoList::InvalidateCache() { @@ -320,11 +324,10 @@ void CargoList::InvalidateCache() } } - /** * Update the cached values to reflect the removal of this packet. - * Decreases count, feeder share and days_in_transit - * @param cp Packet to be removed from cache + * Decreases count, feeder share and days_in_transit. + * @param cp Packet to be removed from cache. */ void VehicleCargoList::RemoveFromCache(const CargoPacket *cp) { @@ -334,8 +337,8 @@ void VehicleCargoList::RemoveFromCache(const CargoPacket *cp) /** * Update the cache to reflect adding of this packet. - * Increases count, feeder share and days_in_transit - * @param cp a new packet to be inserted + * Increases count, feeder share and days_in_transit. + * @param cp New packet to be inserted. */ void VehicleCargoList::AddToCache(const CargoPacket *cp) { @@ -344,7 +347,7 @@ void VehicleCargoList::AddToCache(const CargoPacket *cp) } /** - * Ages the all cargo in this list + * Ages the all cargo in this list. */ void VehicleCargoList::AgeCargo() { @@ -358,7 +361,7 @@ void VehicleCargoList::AgeCargo() } } -/** Invalidates the cached data and rebuild it */ +/** Invalidates the cached data and rebuild it. */ void VehicleCargoList::InvalidateCache() { this->feeder_share = 0; @@ -371,9 +374,9 @@ void VehicleCargoList::InvalidateCache() template class CargoList; template class CargoList; -/** Autoreplace Vehicle -> Vehicle 'transfer' */ +/** Autoreplace Vehicle -> Vehicle 'transfer'. */ template bool CargoList::MoveTo(VehicleCargoList *, uint max_move, MoveToAction mta, CargoPayment *payment, uint data); -/** Cargo unloading at a station */ +/** Cargo unloading at a station. */ template bool CargoList::MoveTo(StationCargoList *, uint max_move, MoveToAction mta, CargoPayment *payment, uint data); -/** Cargo loading at a station */ +/** Cargo loading at a station. */ template bool CargoList::MoveTo(VehicleCargoList *, uint max_move, MoveToAction mta, CargoPayment *payment, uint data); diff --git a/src/cargopacket.h b/src/cargopacket.h index 68ba629cf..c6038fe9e 100644 --- a/src/cargopacket.h +++ b/src/cargopacket.h @@ -25,25 +25,25 @@ struct CargoPacket; /** Type of the pool for cargo packets for a little over 16 million packets. */ typedef Pool CargoPacketPool; -/** The actual pool with cargo packets */ +/** The actual pool with cargo packets. */ extern CargoPacketPool _cargopacket_pool; template class CargoList; extern const struct SaveLoad *GetCargoPacketDesc(); /** - * Container for cargo from the same location and time + * Container for cargo from the same location and time. */ struct CargoPacket : CargoPacketPool::PoolItem<&_cargopacket_pool> { private: - Money feeder_share; ///< Value of feeder pickup to be paid for on delivery of cargo - uint16 count; ///< The amount of cargo in this packet - byte days_in_transit; ///< Amount of days this packet has been in transit - SourceTypeByte source_type; ///< Type of \c source_id - SourceID source_id; ///< Index of source, INVALID_SOURCE if unknown/invalid - StationID source; ///< The station where the cargo came from first - TileIndex source_xy; ///< The origin of the cargo (first station in feeder chain) - TileIndex loaded_at_xy; ///< Location where this cargo has been loaded into the vehicle + Money feeder_share; ///< Value of feeder pickup to be paid for on delivery of cargo. + uint16 count; ///< The amount of cargo in this packet. + byte days_in_transit; ///< Amount of days this packet has been in transit. + SourceTypeByte source_type; ///< Type of \c source_id. + SourceID source_id; ///< Index of source, INVALID_SOURCE if unknown/invalid. + StationID source; ///< The station where the cargo came from first. + TileIndex source_xy; ///< The origin of the cargo (first station in feeder chain). + TileIndex loaded_at_xy; ///< Location where this cargo has been loaded into the vehicle. /** The CargoList caches, thus needs to know about it. */ template friend class CargoList; @@ -59,13 +59,13 @@ public: CargoPacket(StationID source, TileIndex source_xy, uint16 count, SourceType source_type, SourceID source_id); CargoPacket(uint16 count, byte days_in_transit, StationID source, TileIndex source_xy, TileIndex loaded_at_xy, Money feeder_share = 0, SourceType source_type = ST_INDUSTRY, SourceID source_id = INVALID_SOURCE); - /** Destroy the packet */ + /** Destroy the packet. */ ~CargoPacket() { } /** * Gets the number of 'items' in this packet. - * @return the item count + * @return the item count. */ FORCEINLINE uint16 Count() const { @@ -75,7 +75,7 @@ public: /** * Gets the amount of money already paid to earlier vehicles in * the feeder chain. - * @return the feeder share + * @return Feeder share. */ FORCEINLINE Money FeederShare() const { @@ -86,7 +86,7 @@ public: * Gets the number of days this cargo has been in transit. * This number isn't really in days, but in 2.5 days (185 ticks) and * it is capped at 255. - * @return the length this cargo has been in transit + * @return Length this cargo has been in transit. */ FORCEINLINE byte DaysInTransit() const { @@ -94,8 +94,8 @@ public: } /** - * Gets the type of the cargo's source. industry, town or head quarter - * @return the source type + * Gets the type of the cargo's source. industry, town or head quarter. + * @return Source type. */ FORCEINLINE SourceType SourceSubsidyType() const { @@ -103,8 +103,8 @@ public: } /** - * Gets the ID of the cargo's source. An IndustryID, TownID or CompanyID - * @return the source ID + * Gets the ID of the cargo's source. An IndustryID, TownID or CompanyID. + * @return Source ID. */ FORCEINLINE SourceID SourceSubsidyID() const { @@ -112,8 +112,8 @@ public: } /** - * Gets the ID of the station where the cargo was loaded for the first time - * @return the StationID + * Gets the ID of the station where the cargo was loaded for the first time. + * @return StationID. */ FORCEINLINE SourceID SourceStation() const { @@ -121,8 +121,8 @@ public: } /** - * Gets the coordinates of the cargo's source station - * @return the source station's coordinates + * Gets the coordinates of the cargo's source station. + * @return Source station's coordinates. */ FORCEINLINE TileIndex SourceStationXY() const { @@ -130,8 +130,8 @@ public: } /** - * Gets the coordinates of the cargo's last loading station - * @return the last loading station's coordinates + * Gets the coordinates of the cargo's last loading station. + * @return Last loading station's coordinates. */ FORCEINLINE TileIndex LoadedAtXY() const { @@ -145,57 +145,59 @@ public: }; /** - * Iterate over all _valid_ cargo packets from the given start - * @param var the variable used as "iterator" - * @param start the cargo packet ID of the first packet to iterate over + * Iterate over all _valid_ cargo packets from the given start. + * @param var Variable used as "iterator". + * @param start Cargo packet ID of the first packet to iterate over. */ #define FOR_ALL_CARGOPACKETS_FROM(var, start) FOR_ALL_ITEMS_FROM(CargoPacket, cargopacket_index, var, start) /** - * Iterate over all _valid_ cargo packets from the begin of the pool - * @param var the variable used as "iterator" + * Iterate over all _valid_ cargo packets from the begin of the pool. + * @param var Variable used as "iterator". */ #define FOR_ALL_CARGOPACKETS(var) FOR_ALL_CARGOPACKETS_FROM(var, 0) /** - * Simple collection class for a list of cargo packets - * @tparam Tinst The actual instantation of this cargo list + * Simple collection class for a list of cargo packets. + * @tparam Tinst Actual instantation of this cargo list. */ template class CargoList { public: - /** Container with cargo packets */ + /** Container with cargo packets. */ typedef std::list List; - /** The iterator for our container */ + /** The iterator for our container. */ typedef List::iterator Iterator; - /** The const iterator for our container */ + /** The const iterator for our container. */ typedef List::const_iterator ConstIterator; - /** Kind of actions that could be done with packets on move */ + /** Kind of actions that could be done with packets on move. */ enum MoveToAction { - MTA_FINAL_DELIVERY, ///< "Deliver" the packet to the final destination, i.e. destroy the packet - MTA_CARGO_LOAD, ///< Load the packet onto a vehicle, i.e. set the last loaded station ID - MTA_TRANSFER, ///< The cargo is moved as part of a transfer - MTA_UNLOAD, ///< The cargo is moved as part of a forced unload + MTA_FINAL_DELIVERY, ///< "Deliver" the packet to the final destination, i.e. destroy the packet. + MTA_CARGO_LOAD, ///< Load the packet onto a vehicle, i.e. set the last loaded station ID. + MTA_TRANSFER, ///< The cargo is moved as part of a transfer. + MTA_UNLOAD, ///< The cargo is moved as part of a forced unload. }; protected: - uint count; ///< Cache for the number of cargo entities - uint cargo_days_in_transit; ///< Cache for the sum of number of days in transit of each entity; comparable to man-hours + uint count; ///< Cache for the number of cargo entities. + uint cargo_days_in_transit; ///< Cache for the sum of number of days in transit of each entity; comparable to man-hours. - List packets; ///< The cargo packets in this list + List packets; ///< The cargo packets in this list. void AddToCache(const CargoPacket *cp); + void RemoveFromCache(const CargoPacket *cp); public: - /** Create the cargo list */ + /** Create the cargo list. */ CargoList() {} + ~CargoList(); /** * Returns a pointer to the cargo packet list (so you can iterate over it etc). - * @return pointer to the packet list + * @return Pointer to the packet list. */ FORCEINLINE const List *Packets() const { @@ -203,8 +205,8 @@ public: } /** - * Checks whether this list is empty - * @return true if and only if the list is empty + * Checks whether this list is empty. + * @return True if and only if the list is empty. */ FORCEINLINE bool Empty() const { @@ -212,8 +214,8 @@ public: } /** - * Returns the number of cargo entities in this list - * @return the before mentioned number + * Returns the number of cargo entities in this list. + * @return The before mentioned number. */ FORCEINLINE uint Count() const { @@ -221,8 +223,8 @@ public: } /** - * Returns source of the first cargo packet in this list - * @return the before mentioned source + * Returns source of the first cargo packet in this list. + * @return The before mentioned source. */ FORCEINLINE StationID Source() const { @@ -230,8 +232,8 @@ public: } /** - * Returns average number of days in transit for a cargo entity - * @return the before mentioned number + * Returns average number of days in transit for a cargo entity. + * @return The before mentioned number. */ FORCEINLINE uint DaysInTransit() const { @@ -253,23 +255,23 @@ public: */ class VehicleCargoList : public CargoList { protected: - /** The (direct) parent of this class */ + /** The (direct) parent of this class. */ typedef CargoList Parent; - Money feeder_share; ///< Cache for the feeder share + Money feeder_share; ///< Cache for the feeder share. void AddToCache(const CargoPacket *cp); void RemoveFromCache(const CargoPacket *cp); public: - /** The super class ought to know what it's doing */ + /** The super class ought to know what it's doing. */ friend class CargoList; /** The vehicles have a cargo list (and we want that saved). */ friend const struct SaveLoad *GetVehicleDescription(VehicleType vt); /** - * Returns total sum of the feeder share for all packets - * @return the before mentioned number + * Returns total sum of the feeder share for all packets. + * @return The before mentioned number. */ FORCEINLINE Money FeederShare() const { @@ -283,9 +285,9 @@ public: /** * Are two the two CargoPackets mergeable in the context of * a list of CargoPackets for a Vehicle? - * @param cp1 the first CargoPacket - * @param cp2 the second CargoPacket - * @return true if they are mergeable + * @param cp1 First CargoPacket. + * @param cp2 Second CargoPacket. + * @return True if they are mergeable. */ static bool AreMergable(const CargoPacket *cp1, const CargoPacket *cp2) { @@ -302,7 +304,7 @@ public: */ class StationCargoList : public CargoList { public: - /** The super class ought to know what it's doing */ + /** The super class ought to know what it's doing. */ friend class CargoList; /** The stations, via GoodsEntry, have a CargoList. */ friend const struct SaveLoad *GetGoodsDesc(); @@ -310,9 +312,9 @@ public: /** * Are two the two CargoPackets mergeable in the context of * a list of CargoPackets for a Vehicle? - * @param cp1 the first CargoPacket - * @param cp2 the second CargoPacket - * @return true if they are mergeable + * @param cp1 First CargoPacket. + * @param cp2 Second CargoPacket. + * @return True if they are mergeable. */ static bool AreMergable(const CargoPacket *cp1, const CargoPacket *cp2) { -- cgit v1.2.3-70-g09d2