(svn r21844) -Codechange: move documentation towards the code to make it more likely to be updates [a-c].

1 files changed, 85 insertions, 2 deletions

diff --git a/src/cargopacket.cpp b/src/cargopacket.cpp
index 418eb8e83..e73341ff3 100644
--- a/src/cargopacket.cpp
+++ b/src/cargopacket.cpp
@@ -25,14 +25,26 @@ void InitializeCargoPackets()
 	_cargopacket_pool.CleanPool();
 }
 
+/**
+ * Create a new packet for savegame loading.
+ */
 CargoPacket::CargoPacket()
 {
 	this->source_type = ST_INDUSTRY;
 	this->source_id   = INVALID_SOURCE;
 }
 
-/* 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. */
+/**
+ * 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)
+ * @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.
+ */
 CargoPacket::CargoPacket(StationID source, TileIndex source_xy, uint16 count, SourceType source_type, SourceID source_id) :
 	feeder_share(0),
 	count(count),
@@ -46,6 +58,18 @@ CargoPacket::CargoPacket(StationID source, TileIndex source_xy, uint16 count, So
 	this->source_type  = source_type;
 }
 
+/**
+ * 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)
+ */
 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),
 		count(count),
@@ -90,6 +114,7 @@ CargoPacket::CargoPacket(uint16 count, byte days_in_transit, StationID source, T
  *
  */
 
+/** Destroy it ("frees" all cargo packets) */
 template <class Tinst>
 CargoList<Tinst>::~CargoList()
 {
@@ -98,6 +123,11 @@ CargoList<Tinst>::~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
+ */
 template <class Tinst>
 void CargoList<Tinst>::RemoveFromCache(const CargoPacket *cp)
 {
@@ -105,6 +135,11 @@ void CargoList<Tinst>::RemoveFromCache(const CargoPacket *cp)
 	this->cargo_days_in_transit -= cp->days_in_transit * cp->count;
 }
 
+/**
+ * Update the cache to reflect adding of this packet.
+ * Increases count and days_in_transit
+ * @param cp a new packet to be inserted
+ */
 template <class Tinst>
 void CargoList<Tinst>::AddToCache(const CargoPacket *cp)
 {
@@ -112,6 +147,13 @@ void CargoList<Tinst>::AddToCache(const CargoPacket *cp)
 	this->cargo_days_in_transit += cp->days_in_transit * cp->count;
 }
 
+/**
+ * Appends the given cargo packet
+ * @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
+ * @pre cp != NULL
+ */
 template <class Tinst>
 void CargoList<Tinst>::Append(CargoPacket *cp)
 {
@@ -134,6 +176,11 @@ void CargoList<Tinst>::Append(CargoPacket *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
+ */
 template <class Tinst>
 void CargoList<Tinst>::Truncate(uint max_remaining)
 {
@@ -161,6 +208,27 @@ void CargoList<Tinst>::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)
+ * @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
+ *
+ * @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
+ */
 template <class Tinst>
 template <class Tother_inst>
 bool CargoList<Tinst>::MoveTo(Tother_inst *dest, uint max_move, MoveToAction mta, CargoPayment *payment, uint data)
@@ -240,6 +308,7 @@ bool CargoList<Tinst>::MoveTo(Tother_inst *dest, uint max_move, MoveToAction mta
 	return it != packets.end();
 }
 
+/** Invalidates the cached data and rebuild it */
 template <class Tinst>
 void CargoList<Tinst>::InvalidateCache()
 {
@@ -252,18 +321,31 @@ void CargoList<Tinst>::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
+ */
 void VehicleCargoList::RemoveFromCache(const CargoPacket *cp)
 {
 	this->feeder_share -= cp->feeder_share;
 	this->Parent::RemoveFromCache(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
+ */
 void VehicleCargoList::AddToCache(const CargoPacket *cp)
 {
 	this->feeder_share += cp->feeder_share;
 	this->Parent::AddToCache(cp);
 }
 
+/**
+ * Ages the all cargo in this list
+ */
 void VehicleCargoList::AgeCargo()
 {
 	for (ConstIterator it(this->packets.begin()); it != this->packets.end(); it++) {
@@ -276,6 +358,7 @@ void VehicleCargoList::AgeCargo()
 	}
 }
 
+/** Invalidates the cached data and rebuild it */
 void VehicleCargoList::InvalidateCache()
 {
 	this->feeder_share = 0;