summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authoralberth <alberth@openttd.org>2009-12-05 21:39:28 +0000
committeralberth <alberth@openttd.org>2009-12-05 21:39:28 +0000
commit41d2214e7e5a72be58e1b97a7f5f04a1b4b6660b (patch)
tree91d859e91169cf51c32960784114923f3bc6bccf
parent29606c0de66de3c40074eb086410ef39951e0d86 (diff)
downloadopenttd-41d2214e7e5a72be58e1b97a7f5f04a1b4b6660b.tar.xz
(svn r18413) -Doc: Added doxygen strings for cargo-type related enums, structs, and functions.
-rw-r--r--src/cargo_type.h21
-rw-r--r--src/cargotype.cpp15
-rw-r--r--src/cargotype.h55
-rw-r--r--src/table/cargo_const.h4
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', },