(svn r17727) -Codechange: some coding style and documentation fixes

3 files changed, 73 insertions, 43 deletions

diff --git a/src/cargopacket.cpp b/src/cargopacket.cpp
index 8561bf069..6caceac98 100644
--- a/src/cargopacket.cpp
+++ b/src/cargopacket.cpp
@@ -18,6 +18,9 @@
 CargoPacketPool _cargopacket_pool("CargoPacket");
 INSTANTIATE_POOL_METHODS(CargoPacket)
 
+/**
+ * Initialize, i.e. clean, the pool with cargo packets.
+ */
 void InitializeCargoPackets()
 {
 	_cargopacket_pool.CleanPool();
@@ -28,7 +31,7 @@ CargoPacket::CargoPacket(StationID source, uint16 count, SourceType source_type,
 	source(source),
 	source_id(source_id)
 {
-	this->source_type     = source_type;
+	this->source_type = source_type;
 
 	if (source != INVALID_STATION) {
 		assert(count != 0);
@@ -67,48 +70,48 @@ CargoPacket::CargoPacket(uint16 count, byte days_in_transit, Money feeder_share,
 
 CargoList::~CargoList()
 {
-	while (!packets.empty()) {
-		delete packets.front();
-		packets.pop_front();
+	while (!this->packets.empty()) {
+		delete this->packets.front();
+		this->packets.pop_front();
 	}
 }
 
 void CargoList::AgeCargo()
 {
-	if (empty) return;
+	if (this->empty) return;
 
 	uint dit = 0;
-	for (List::const_iterator it = packets.begin(); it != packets.end(); it++) {
+	for (List::const_iterator it = this->packets.begin(); it != this->packets.end(); it++) {
 		if ((*it)->days_in_transit != 0xFF) (*it)->days_in_transit++;
 		dit += (*it)->days_in_transit * (*it)->count;
 	}
-	days_in_transit = dit / count;
+	this->days_in_transit = dit / count;
 }
 
 void CargoList::Append(CargoPacket *cp)
 {
 	assert(cp != NULL);
 
-	for (List::iterator it = packets.begin(); it != packets.end(); it++) {
+	for (List::iterator it = this->packets.begin(); it != this->packets.end(); it++) {
 		if ((*it)->SameSource(cp) && (*it)->count + cp->count <= CargoPacket::MAX_COUNT) {
 			(*it)->count        += cp->count;
 			(*it)->feeder_share += cp->feeder_share;
 			delete cp;
 
-			InvalidateCache();
+			this->InvalidateCache();
 			return;
 		}
 	}
 
 	/* The packet could not be merged with another one */
-	packets.push_back(cp);
-	InvalidateCache();
+	this->packets.push_back(cp);
+	this->InvalidateCache();
 }
 
 
 void CargoList::Truncate(uint count)
 {
-	for (List::iterator it = packets.begin(); it != packets.end(); it++) {
+	for (List::iterator it = this->packets.begin(); it != this->packets.end(); it++) {
 		uint local_count = (*it)->count;
 		if (local_count <= count) {
 			count -= local_count;
@@ -119,14 +122,14 @@ void CargoList::Truncate(uint count)
 		count = 0;
 	}
 
-	while (!packets.empty()) {
-		CargoPacket *cp = packets.back();
+	while (!this->packets.empty()) {
+		CargoPacket *cp = this->packets.back();
 		if (cp->count != 0) break;
 		delete cp;
-		packets.pop_back();
+		this->packets.pop_back();
 	}
 
-	InvalidateCache();
+	this->InvalidateCache();
 }
 
 bool CargoList::MoveTo(CargoList *dest, uint count, CargoList::MoveToAction mta, CargoPayment *payment, uint data)
@@ -135,11 +138,11 @@ bool CargoList::MoveTo(CargoList *dest, uint count, CargoList::MoveToAction mta,
 	assert(mta == MTA_UNLOAD || mta == MTA_CARGO_LOAD || payment != NULL);
 	CargoList tmp;
 
-	while (!packets.empty() && count > 0) {
+	while (!this->packets.empty() && count > 0) {
 		CargoPacket *cp = *packets.begin();
 		if (cp->count <= count) {
 			/* Can move the complete packet */
-			packets.remove(cp);
+			this->packets.remove(cp);
 			switch (mta) {
 				case MTA_FINAL_DELIVERY:
 					if (cp->source == data) {
@@ -195,7 +198,7 @@ bool CargoList::MoveTo(CargoList *dest, uint count, CargoList::MoveToAction mta,
 		}
 	}
 
-	bool remaining = !packets.empty();
+	bool remaining = !this->packets.empty();
 
 	if (mta == MTA_FINAL_DELIVERY && !tmp.Empty()) {
 		/* There are some packets that could not be delivered at the station, put them back */
@@ -204,28 +207,27 @@ bool CargoList::MoveTo(CargoList *dest, uint count, CargoList::MoveToAction mta,
 	}
 
 	if (dest != NULL) dest->InvalidateCache();
-	InvalidateCache();
+	this->InvalidateCache();
 
 	return remaining;
 }
 
 void CargoList::InvalidateCache()
 {
-	empty = packets.empty();
-	count = 0;
-	feeder_share = 0;
-	source = INVALID_STATION;
-	days_in_transit = 0;
+	this->empty = this->packets.empty();
+	this->count = 0;
+	this->feeder_share = 0;
+	this->source = INVALID_STATION;
+	this->days_in_transit = 0;
 
-	if (empty) return;
+	if (this->empty) return;
 
 	uint dit = 0;
-	for (List::const_iterator it = packets.begin(); it != packets.end(); it++) {
-		count        += (*it)->count;
-		dit          += (*it)->days_in_transit * (*it)->count;
-		feeder_share += (*it)->feeder_share;
+	for (List::const_iterator it = this->packets.begin(); it != this->packets.end(); it++) {
+		this->count        += (*it)->count;
+		dit                += (*it)->days_in_transit * (*it)->count;
+		this->feeder_share += (*it)->feeder_share;
 	}
-	days_in_transit = dit / count;
-	source = (*packets.begin())->source;
+	this->days_in_transit = dit / count;
+	this->source = (*packets.begin())->source;
 }
-
diff --git a/src/cargopacket.h b/src/cargopacket.h
index 8bddaf3d4..dd96ed7f0 100644
--- a/src/cargopacket.h
+++ b/src/cargopacket.h
@@ -19,11 +19,13 @@
 #include "cargo_type.h"
 #include <list>
 
+/** Unique identifier for a single cargo packet. */
 typedef uint32 CargoPacketID;
 struct CargoPacket;
 
-/** We want to use a pool */
+/** Type of the pool for cargo packets. */
 typedef Pool<CargoPacket, CargoPacketID, 1024, 1048576> CargoPacketPool;
+/** The actual pool with cargo packets */
 extern CargoPacketPool _cargopacket_pool;
 
 class CargoList;
@@ -51,7 +53,7 @@ public:
 	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
 	StationID source;           ///< The station where the cargo came from first
-	SourceTypeByte source_type; ///< Type of #source_id
+	SourceTypeByte source_type; ///< Type of \c source_id
 	SourceID source_id;         ///< Index of source, INVALID_SOURCE if unknown/invalid
 
 	/**
@@ -118,8 +120,10 @@ public:
 	 */
 	FORCEINLINE bool SameSource(const CargoPacket *cp) const
 	{
-		return this->source_xy == cp->source_xy && this->days_in_transit == cp->days_in_transit &&
-				this->source_type == cp->source_type && this->source_id == cp->source_id;
+		return this->source_xy    == cp->source_xy &&
+				this->days_in_transit == cp->days_in_transit &&
+				this->source_type     == cp->source_type &&
+				this->source_id       == cp->source_id;
 	}
 
 	static void InvalidateAllFrom(SourceType src_type, SourceID src);
@@ -166,6 +170,7 @@ private:
 	uint days_in_transit; ///< Cache for the number of days in transit
 
 public:
+	/** The GoodsEntry has a CargoList. */
 	friend const struct SaveLoad *GetGoodsDesc();
 
 	/** Create the cargo list */
@@ -177,7 +182,10 @@ public:
 	 * Returns a pointer to the cargo packet list (so you can iterate over it etc).
 	 * @return pointer to the packet list
 	 */
-	FORCEINLINE const CargoList::List *Packets() const { return &this->packets; }
+	FORCEINLINE const CargoList::List *Packets() const
+	{
+		return &this->packets;
+	}
 
 	/**
 	 * Ages the all cargo in this list
@@ -188,31 +196,46 @@ public:
 	 * Checks whether this list is empty
 	 * @return true if and only if the list is empty
 	 */
-	FORCEINLINE bool Empty() const { return this->empty; }
+	FORCEINLINE bool Empty() const
+	{
+		return this->empty;
+	}
 
 	/**
 	 * Returns the number of cargo entities in this list
 	 * @return the before mentioned number
 	 */
-	FORCEINLINE uint Count() const { return this->count; }
+	FORCEINLINE uint Count() const
+	{
+		return this->count;
+	}
 
 	/**
 	 * Returns total sum of the feeder share for all packets
 	 * @return the before mentioned number
 	 */
-	FORCEINLINE Money FeederShare() const { return this->feeder_share; }
+	FORCEINLINE Money FeederShare() const
+	{
+		return this->feeder_share;
+	}
 
 	/**
 	 * Returns source of the first cargo packet in this list
 	 * @return the before mentioned source
 	 */
-	FORCEINLINE StationID Source() const { return this->source; }
+	FORCEINLINE StationID Source() const
+	{
+		return this->source;
+	}
 
 	/**
 	 * Returns average number of days in transit for a cargo entity
 	 * @return the before mentioned number
 	 */
-	FORCEINLINE uint DaysInTransit() const { return this->days_in_transit; }
+	FORCEINLINE uint DaysInTransit() const
+	{
+		return this->days_in_transit;
+	}
 
 
 	/**
diff --git a/src/saveload/station_sl.cpp b/src/saveload/station_sl.cpp
index 5e11c04c5..cce636046 100644
--- a/src/saveload/station_sl.cpp
+++ b/src/saveload/station_sl.cpp
@@ -196,6 +196,11 @@ static const SaveLoad _station_speclist_desc[] = {
 	SLE_END()
 };
 
+/**
+ * Wrapper function to get the GoodsEntry's internal structure while
+ * some of the variables itself are private.
+ * @return the saveload description for GoodsEntry.
+ */
 const SaveLoad *GetGoodsDesc()
 {
 	static const SaveLoad goods_desc[] = {