(svn r18413) -Doc: Added doxygen strings for cargo-type related enums, structs, and functions.

4 files changed, 62 insertions, 33 deletions

diff --git a/src/cargo_type.h b/src/cargo_type.h
index 8706b4373..8d9a1a825 100644
--- a/src/cargo_type.h
+++ b/src/cargo_type.h
@@ -14,6 +14,11 @@
 
 #include "core/enum_type.hpp"
 
+/**
+ * Cargo slots to indicate a cargo type within a game.
+ * Numbers are re-used between different climates.
+ * @see CargoTypes
+ */
 typedef byte CargoID;
 
 /** Available types of cargo */
@@ -58,33 +63,41 @@ enum CargoTypes {
 	CT_PLASTIC      = 10,
 	CT_FIZZY_DRINKS = 11,
 
-	NUM_CARGO       = 32,
+	NUM_CARGO       = 32,   ///< Maximal number of cargo types in a game.
 
-	CT_NO_REFIT     = 0xFE,
-	CT_INVALID      = 0xFF
+	CT_NO_REFIT     = 0xFE, ///< Do not refit cargo of a vehicle (used in vehicle orders and auto-replace/auto-new).
+	CT_INVALID      = 0xFF, ///< Invalid cargo type.
 };
 
 /** Class for storing amounts of cargo */
 struct CargoArray {
 private:
-	uint amount[NUM_CARGO];
+	uint amount[NUM_CARGO]; ///< Amount of each type of cargo.
 
 public:
+	/** Default constructor. */
 	FORCEINLINE CargoArray()
 	{
 		this->Clear();
 	}
 
+	/** Reset all entries. */
 	FORCEINLINE void Clear()
 	{
 		memset(this->amount, 0, sizeof(this->amount));
 	}
 
+	/** Read/write access to an amount of a specific cargo type.
+	 * @param cargo Cargo type to access.
+	 */
 	FORCEINLINE uint &operator[](CargoID cargo)
 	{
 		return this->amount[cargo];
 	}
 
+	/** Read-only access to an amount of a specific cargo type.
+	 * @param cargo Cargo type to access.
+	 */
 	FORCEINLINE const uint &operator[](CargoID cargo) const
 	{
 		return this->amount[cargo];
diff --git a/src/cargotype.cpp b/src/cargotype.cpp
index 6920cf17f..3e2e742d0 100644
--- a/src/cargotype.cpp
+++ b/src/cargotype.cpp
@@ -20,10 +20,14 @@
 
 CargoSpec CargoSpec::array[NUM_CARGO];
 
-/* Bitmask of cargo types available */
+/** Bitmask of cargo types available.
+ * Initialized during a call to #SetupCargoForClimate.
+ */
 uint32 _cargo_mask;
 
-
+/** Set up the default cargo types for the given landscape type.
+ * @param l Landscape
+ */
 void SetupCargoForClimate(LandscapeID l)
 {
 	assert(l < lengthof(_default_climate_cargo));
@@ -60,7 +64,10 @@ void SetupCargoForClimate(LandscapeID l)
 	}
 }
 
-
+/** Get the cargo ID by cargo label.
+ * @param cl Cargo type to get.
+ * @return ID number if the cargo exists, else #CT_INVALID
+ */
 CargoID GetCargoIDByLabel(CargoLabel cl)
 {
 	const CargoSpec *cs;
@@ -75,7 +82,7 @@ CargoID GetCargoIDByLabel(CargoLabel cl)
 
 /** Find the CargoID of a 'bitnum' value.
  * @param bitnum 'bitnum' to find.
- * @return First CargoID with the given bitnum, or CT_INVALID if not found.
+ * @return First CargoID with the given bitnum, or #CT_INVALID if not found or if the provided \a bitnum is invalid.
  */
 CargoID GetCargoIDByBitnum(uint8 bitnum)
 {
diff --git a/src/cargotype.h b/src/cargotype.h
index f8ecdbdcc..29c7b54ec 100644
--- a/src/cargotype.h
+++ b/src/cargotype.h
@@ -18,17 +18,20 @@
 #include "strings_type.h"
 #include "landscape_type.h"
 
+/** Globally unique label of a cargo type. */
 typedef uint32 CargoLabel;
 
+/** Town growth effect when delivering cargo. */
 enum TownEffect {
-	TE_NONE,
-	TE_PASSENGERS,
-	TE_MAIL,
-	TE_GOODS,
-	TE_WATER,
-	TE_FOOD,
+	TE_NONE,       ///< Cargo has no effect.
+	TE_PASSENGERS, ///< Cargo behaves passenger-like.
+	TE_MAIL,       ///< Cargo behaves mail-like.
+	TE_GOODS,      ///< Cargo behaves goods/candy-like.
+	TE_WATER,      ///< Cargo behaves water-like.
+	TE_FOOD,       ///< Cargo behaves food/fizzy-drinks-like.
 };
 
+/** Cargo classes. */
 enum CargoClass {
 	CC_NOAVAILABLE  = 0,       ///< No cargo class has been specified
 	CC_PASSENGERS   = 1 <<  0, ///< Passengers
@@ -44,32 +47,33 @@ enum CargoClass {
 	CC_SPECIAL      = 1 << 15  ///< Special bit used for livery refit tricks instead of normal cargoes.
 };
 
-static const byte INVALID_CARGO = 0xFF;
+static const byte INVALID_CARGO = 0xFF; ///< Constant representing invalid cargo
 
+/** Specification of a cargo type. */
 struct CargoSpec {
-	uint8 bitnum;
-	CargoLabel label;
+	uint8 bitnum;                    ///< Cargo bit number, is #INVALID_CARGO for a non-used spec.
+	CargoLabel label;                ///< Unique label of the cargo type.
 	uint8 legend_colour;
 	uint8 rating_colour;
-	uint8 weight;
+	uint8 weight;                    ///< Weight of a single unit of this cargo type in 1/16 ton (62.5 kg).
 	uint16 initial_payment;
 	uint8 transit_days[2];
 
-	bool is_freight;
-	TownEffect town_effect; ///< The effect this cargo type has on towns
-	uint16 multipliertowngrowth;
-	uint8 callback_mask;         ///< Bitmask of cargo callbacks that have to be called
+	bool is_freight;                 ///< Cargo type is considered to be freight (affects train freight multiplier).
+	TownEffect town_effect;          ///< The effect that delivering this cargo type has on towns. Also affects destination of subsidies.
+	uint16 multipliertowngrowth;     ///< Size of the effect.
+	uint8 callback_mask;             ///< Bitmask of cargo callbacks that have to be called
 
-	StringID name;
-	StringID name_single;
-	StringID units_volume;
-	StringID quantifier;
-	StringID abbrev;
+	StringID name;                   ///< Name of this type of cargo.
+	StringID name_single;            ///< Name of a single entity of this type of cargo.
+	StringID units_volume;           ///< Name of a single unit of cargo of this type.
+	StringID quantifier;             ///< Text for multiple units of cargo of this type.
+	StringID abbrev;                 ///< Two letter abbreviation for this cargo type.
 
-	SpriteID sprite;
+	SpriteID sprite;                 ///< Icon to display this cargo type, may be \c 0xFFF (which means to resolve an action123 chain).
 
-	uint16 classes;
-	const struct GRFFile *grffile;   ///< NewGRF where 'group' belongs to
+	uint16 classes;                  ///< Classes of this cargo type. @see CargoClass
+	const struct GRFFile *grffile;   ///< NewGRF where #group belongs to.
 	const struct SpriteGroup *group;
 
 	Money current_payment;
@@ -123,12 +127,15 @@ private:
 
 extern uint32 _cargo_mask;
 
-/* Set up the default cargo types for the given landscape type */
 void SetupCargoForClimate(LandscapeID l);
-/* Get the cargo ID with the cargo label */
 CargoID GetCargoIDByLabel(CargoLabel cl);
 CargoID GetCargoIDByBitnum(uint8 bitnum);
 
+/** Does cargo \a c have cargo class \a cc?
+ * @param c  Cargo type.
+ * @param cc Cargo class.
+ * @return The type fits in the class.
+ */
 static inline bool IsCargoInClass(CargoID c, CargoClass cc)
 {
 	return (CargoSpec::Get(c)->classes & cc) != 0;
diff --git a/src/table/cargo_const.h b/src/table/cargo_const.h
index 686251580..17c2a7753 100644
--- a/src/table/cargo_const.h
+++ b/src/table/cargo_const.h
@@ -9,8 +9,10 @@
 
 /** @file cargo_const.h Table of all default cargo types */
 
+/** Construction macro for a #CargoSpec structure. */
 #define MK(bt, label, c, e, f, g, h, fr, te, ks1, ks2, ks3, ks4, ks5, l, m) \
 		{bt, label, c, c, e, f, {g, h}, fr, te, 0, 0, ks1, ks2, ks3, ks4, ks5, l, m, NULL, NULL, 0}
+/** Cargo types available by default. */
 static const CargoSpec _default_cargo[] = {
 	MK(  0, 'PASS', 152,  1, 3185,  0,  24, false, TE_PASSENGERS,
 		STR_CARGO_PLURAL_PASSENGERS,     STR_CARGO_SINGULAR_PASSENGER,      STR_PASSENGERS, STR_QUANTITY_PASSENGERS,   STR_ABBREV_PASSENGERS,
@@ -161,7 +163,7 @@ static const CargoSpec _default_cargo[] = {
 };
 
 
-/* Table of which cargo types are available in each climate, by default */
+/** Table of cargo types available in each climate, by default */
 static const CargoLabel _default_climate_cargo[NUM_LANDSCAPE][12] = {
 	{ 'PASS', 'COAL', 'MAIL', 'OIL_', 'LVST', 'GOOD', 'GRAI', 'WOOD', 'IORE', 'STEL', 'VALU',     33, },
 	{ 'PASS', 'COAL', 'MAIL', 'OIL_', 'LVST', 'GOOD', 'WHEA', 'WOOD',     34, 'PAPR', 'GOLD', 'FOOD', },