From bb4d83214685f5ae62ed8c9377c2f028e2e08c2b Mon Sep 17 00:00:00 2001 From: alberth Date: Sun, 13 Mar 2011 16:43:00 +0000 Subject: (svn r22239) -Doc: Further engine doxyment additions. --- src/engine.cpp | 15 ++++++++++++++- src/engine_base.h | 26 +++++++++++++++----------- src/engine_type.h | 14 +++++++------- 3 files changed, 36 insertions(+), 19 deletions(-) (limited to 'src') diff --git a/src/engine.cpp b/src/engine.cpp index 8774b0b3e..fa51e7c59 100644 --- a/src/engine.cpp +++ b/src/engine.cpp @@ -542,13 +542,21 @@ static void CheckRailIntroduction() void ShowEnginePreviewWindow(EngineID engine); -/* Determine if an engine type is a wagon (and not a loco) */ +/** + * Determine whether an engine type is a wagon (and not a loco). + * @param index %Engine getting queried. + * @return Whether the queried engine is a wagon. + */ static bool IsWagon(EngineID index) { const Engine *e = Engine::Get(index); return e->type == VEH_TRAIN && e->u.rail.railveh_type == RAILVEH_WAGON; } +/** + * Update #reliability of engine \a e, (if needed) update the engine GUIs. + * @param e %Engine to update. + */ static void CalcEngineReliability(Engine *e) { uint age = e->age; @@ -682,6 +690,11 @@ void StartupEngines() InvalidateWindowClassesData(WC_BUILD_VEHICLE); } +/** + * Company \a company accepts engine \a eid for preview. + * @param eid Engine being accepted (is under preview). + * @param company Current company previewing the engine. + */ static void AcceptEnginePreview(EngineID eid, CompanyID company) { Engine *e = Engine::Get(eid); diff --git a/src/engine_base.h b/src/engine_base.h index a8e09129a..a2dd0b1dd 100644 --- a/src/engine_base.h +++ b/src/engine_base.h @@ -23,19 +23,23 @@ typedef Pool EnginePool; extern EnginePool _engine_pool; struct Engine : EnginePool::PoolItem<&_engine_pool> { - char *name; ///< Custom name of engine - Date intro_date; + char *name; ///< Custom name of engine. + Date intro_date; ///< Date of introduction of the engine. Date age; - uint16 reliability; - uint16 reliability_spd_dec; - uint16 reliability_start, reliability_max, reliability_final; - uint16 duration_phase_1, duration_phase_2, duration_phase_3; - byte flags; - uint8 preview_company_rank; - byte preview_wait; - CompanyMask company_avail; + uint16 reliability; ///< Current reliability of the engine. + uint16 reliability_spd_dec; ///< Speed of reliability decay between services (per day). + uint16 reliability_start; ///< Initial reliability of the engine. + uint16 reliability_max; ///< Maximal reliability of the engine. + uint16 reliability_final; ///< Final reliability of the engine. + uint16 duration_phase_1; ///< First reliability phase in months, increasing reliability from #reliability_start to #reliability_max. + uint16 duration_phase_2; ///< Second reliability phase in months, keeping #reliability_max. + uint16 duration_phase_3; ///< Third reliability phase on months, decaying to #reliability_final. + byte flags; ///< Flags of the engine. @see EngineFlags + uint8 preview_company_rank; ///< Rank of the company that is offered a preview. \c 0xFF means no company. + byte preview_wait; ///< Daily countdown timer for timeout of offering the engine to the #preview_company_rank company. + CompanyMask company_avail; ///< Bit for each company whether the engine is available for that company. uint8 original_image_index; ///< Original vehicle image index, thus the image index of the overridden vehicle - VehicleType type; ///< type, ie VEH_ROAD, VEH_TRAIN, etc. + VehicleType type; ///< %Vehicle type, ie #VEH_ROAD, #VEH_TRAIN, etc. EngineInfo info; diff --git a/src/engine_type.h b/src/engine_type.h index 4b148b07c..65ba029b2 100644 --- a/src/engine_type.h +++ b/src/engine_type.h @@ -90,12 +90,12 @@ struct AircraftVehicleInfo { byte image_index; byte cost_factor; byte running_cost; - byte subtype; + byte subtype; ///< Type of aircraft. @see AircraftSubTypeBits SoundID sfx; byte acceleration; uint16 max_speed; ///< Maximum speed (1 unit = 8 mph = 12.8 km-ish/h) - byte mail_capacity; - uint16 passenger_capacity; + byte mail_capacity; ///< Mail capacity (bags). + uint16 passenger_capacity; ///< Passenger capacity (persons). }; /** Information about a road vehicle. */ @@ -119,16 +119,16 @@ struct RoadVehicleInfo { * @see table/engines.h */ struct EngineInfo { - Date base_intro; + Date base_intro; ///< Basic date of engine introduction (without random parts). Year lifelength; ///< Lifetime of a single vehicle - Year base_life; ///< Basic duration of engine availability (without random parts) + Year base_life; ///< Basic duration of engine availability (without random parts). \c 0xFF means infinite life. byte decay_speed; byte load_amount; - byte climates; + byte climates; ///< Climates supported by the engine. CargoID cargo_type; uint32 refit_mask; byte refit_cost; - byte misc_flags; + byte misc_flags; ///< Miscellaneous flags. @see EngineMiscFlags byte callback_mask; ///< Bitmask of vehicle callbacks that have to be called int8 retire_early; ///< Number of years early to retire vehicle StringID string_id; ///< Default name of engine -- cgit v1.2.3-70-g09d2