# HG changeset patch # User alberth # Date 1260049168 0 # Node ID 0ee48164ffe21098669132882d22a729f49179f9 # Parent 8a9a3fcfabe67241603fd2006769b0103d7e8e56 (svn r18413) -Doc: Added doxygen strings for cargo-type related enums, structs, and functions. diff --git a/src/cargo_type.h b/src/cargo_type.h --- 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 @@ 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 --- 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 @@ } } - +/** 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 @@ /** 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 --- 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 @@ 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 @@ 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 --- 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 @@ }; -/* 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', },