(svn r22239) -Doc: Further engine doxyment additions.

3 files changed, 36 insertions, 19 deletions

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<Engine, EngineID, 64, 64000> 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